Back to search
atlas-session-lifecycle
SkillGitHub
Session lifecycle management for Claude Code — persistent memory, soul purpose, reconcile, harvest, archive
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/anombyte93--atlas-session-lifecycle)HTML
<a href="/listings/anombyte93--atlas-session-lifecycle"><img src="/api/listings/anombyte93--atlas-session-lifecycle/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash
Then run `/start` in any Claude Code project.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 305 lines · 3 findings marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Atlas Session Lifecycle
- [](https://github.com/anombyte93/atlas-session-lifecycle/releases) [](https://opensource.org/licenses/MIT) [](https://github.com/anombyte93/atlas-session-lifecycle/stargazers) [](https://github.com/anombyte93/atlas-session-lifecycle/commits/main) [](https://github.com/anombyte93/atlas-session-lifecycle/issues)
- Persistent project memory and session lifecycle management for Claude Code.
- > **Featured in**: [I just delivered on a $30,000 contract thanks to Claude Code](https://www.reddit.com/r/ClaudeAI/comments/1r0n1qz/i_just_delivered_on_a_30000_contract_thanks_to/) (r/ClaudeAI)
- ---
- ## Install
- ```bash
- curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 14 on GitHub
- ```
- Then run `/start` in any Claude Code project.
- ---
- ## What It Does
- Claude Code has no persistent memory between sessions. Every new conversation starts from zero. This creates three compounding problems:
- - **No persistent memory** -- Context, decisions, and progress are lost between sessions. You re-explain the same things every time.
- - **Project sprawl** -- Files accumulate at the project root with no organization. Scripts, docs, configs, and logs pile up across sessions.
- - **No lifecycle management** -- Projects have goals, but no mechanism to track progress, verify completion, or transition to new objectives.
- `/start` solves all three with a structured five-file memory bank, automatic file organization, and a soul purpose lifecycle that tracks your project from inception through completion.
- ---
- ## How It Works
- `/start` auto-detects which mode to run based on directory state:
- ```
- /start
- |
- +-- session-context/ exists? --> Reconcile Mode
- | +-- Validate & repair session files
- | +-- Refresh CLAUDE.md via /init
- | +-- Self-assess soul purpose status
- | +-- Offer: Continue / Close / Redefine
- | +-- Harvest learnings on closure
- |
- +-- No session-context/ -------> Init Mode
- +-- Capture soul purpose
- +-- Bootstrap 5-file memory bank
- +-- Organize root files
- +-- Generate CLAUDE.md
- +-- Onboard Ralph Loop
- ```
- ### Init Mode (first run)
- Triggered when `session-context/` does not exist.
- - Captures your project's **soul purpose** -- the single objective this project exists to achieve
- - Detects environment (git status, existing files, tech stack)
- - Bootstraps `session-context/` with 5 memory bank files from immutable templates
- - Scans root-level files and proposes an organization map (scripts, docs, config, logs)
- - Generates or updates `CLAUDE.md` with project structure and governance sections
- - Onboards Ralph Loop (automatic, manual, or skip)
- ### Reconcile Mode (returning)
- Triggered when `session-context/` already exists.
- - Validates and repairs session files from templates if corrupted
- - Runs Claude's `/init` to refresh `CLAUDE.md` from current codebase state
- - Reads soul purpose and active context to understand where you left off
- - Self-assesses soul purpose completion (clearly incomplete, probably complete, uncertain)
- - Presents lifecycle decision: **Continue**, **Close**, or **Redefine** soul purpose
- - Harvests durable knowledge on closure -- promotes decisions, patterns, and troubleshooting entries
- ### Capability Inventory
- When `/start` runs in Reconcile mode (or when you run `/sync --full`), it generates a comprehensive capability inventory:
- - **MCP Tools**: All available tools with test coverage status
- - **Security Claims**: Security-related features needing verification
- - **Feature Claims**: What the project claims vs what's tested
- - **Test Gaps**: Untested code identified by priority
- The inventory lives in `session-context/CLAUDE-capability-inventory.md` and is used by `/research-before-coding` to identify what needs validation testing. Results are cached based on git HEAD, so regeneration only happens when your code changes.
- ### Stepback (bundled skill)
- Also included: `/stepback` -- a strategic reassessment protocol for when debugging goes sideways. If you've hit the same error after 2+ fix attempts, `/stepback` forces you to zoom out:
- 1. Inventory all fix attempts and their assumptions
- 2. Find the common thread across failures
- 3. Research the architecture (mandatory Perplexity queries)
- 4. Test the broadest hypothesis first
- 5. Present symptom-level vs architecture-level fix options
- Invoked separately via `/stepback` or `/atlas-session-lifecycle:stepback`.
- ---
- ## Session Memory Bank
- Five files in `session-context/` give Claude persistent memory across sessions:
- | File | Purpose |
- |------|---------|
- | `CLAUDE-activeContext.md` | Current session state, goals, and progress |
- | `CLAUDE-decisions.md` | Architecture decisions and rationale |
- | `CLAUDE-patterns.md` | Established code patterns and conventions |
- | `CLAUDE-troubleshooting.md` | Common issues and proven solutions |
- | `CLAUDE-soul-purpose.md` | Soul purpose definition and completion criteria |
- All files use a structured entry format with timestamps, 5W1H context, git references, and potential issues.
- ---
- ## Soul Purpose Lifecycle
- Every project has a soul purpose -- the single objective it exists to achieve.
- ```
- Define --> Work --> Reconcile --> Assess --> Close or Continue
- | | |
- | | +--> Harvest learnings
- | | +--> Archive purpose
- | | +--> Redefine (optional)
- | |
- | +--> Self-assess completion
- | +--> Optional doubt agent verification
- | +--> User decides (never AI)
- |
- +--> Captured during Init Mode
- ```
- **Key invariant**: The AI never closes a soul purpose. It assesses and suggests; the user decides.
- ---
- ## Installation
- ### One-liner (skill mode, default)
- ```bash
- curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 145 on GitHub
- ```
- Installs to `~/.claude/skills/start/`. The SKILL.md orchestrator and `session-init.py` script are placed together.
- ### Plugin mode
- ```bash
- curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash -s -- --plugin
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 153 on GitHub
- ```
- Installs to `~/.claude/plugins/atlas-session-lifecycle/` with full plugin structure including `plugin.json`.
- ### Manual install
- ```bash
- git clone https://github.com/anombyte93/atlas-session-lifecycle.git
- cd atlas-session-lifecycle
- ./install.sh
- ```
- Or copy files directly:
- ```bash
- mkdir -p ~/.claude/skills/start
- cp skills/start/SKILL.md ~/.claude/skills/start/SKILL.md
- cp scripts/session-init.py ~/.claude/skills/start/session-init.py
- chmod +x ~/.claude/skills/start/session-init.py
- mkdir -p ~/claude-session-init-templates
- cp templates/* ~/claude-session-init-templates/
- ```
- ### Version toggle
- ```bash
- # Install v1 (monolithic SKILL.md, no script)
- ./install.sh --version v1
- # Revert from v2 back to v1 (backs up v2 files first)
- ./install.sh --revert
- # Pull latest version and reinstall
- ./install.sh --update
- ```
- ### Auto-update
- The installer records a last-checked timestamp. On each run, if more than 24 hours have passed since the last check, it queries GitHub for newer releases and prompts you to update.
- ---
- ## Configuration
- ### custom.md
- Edit `custom.md` in the plugin root (or `~/.claude/skills/start/custom.md` for skill installs) to modify `/start` behavior. Write plain English instructions — no code needed. The AI reads these at each lifecycle phase and follows them.
- Three headings control when your instructions apply:
- ```markdown
- ## During Init
- - After brainstorming, always suggest a git branching strategy
- - Skip file organization for monorepo projects
- - Always ask about deployment target (local, cloud, edge)
- ## During Reconcile
- - Check for uncommitted changes before assessing soul purpose
- - If soul purpose mentions "API", verify endpoints are documented
- - Always show a progress percentage estimate
- ## Always
- - Keep tone direct and concise. No fluff.
- - When creating session context entries, include the git branch name
- - Never suggest closing a soul purpose unless all tests pass
- ```
- **How it works**: The skill reads `custom.md` at specific points — during init (after session-context is bootstrapped), during reconcile (after reading context, before assessment), and always (both modes). Your instructions augment the default behavior; they don't replace the skill logic.
- **Examples of what you can customize**:
- - Tone and verbosity of responses
- - Extra questions to ask during brainstorm
- - Conditions for when to suggest soul purpose closure
- - Project-specific checks during reconcile
- - Integration with other tools or workflows
- ### Ralph Loop
- During Init, the skill asks how Ralph Loop should operate:
- - **Automatic** -- starts Ralph Loop after setup with configurable intensity (small, medium, long)
- - **Manual** -- user triggers each iteration explicitly
- - **Skip** -- no Ralph Loop
- The preference is stored in `CLAUDE.md` and respected on subsequent Reconcile runs.
- ---
- ## Upgrading from v1
- v2 is a backward-compatible evolution. Your existing `session-context/` files, templates, and project structure are unchanged.
- The main difference: v1 was a single 867-line SKILL.md where Claude interpreted all operations from prose. v2 extracts deterministic operations into `session-init.py` (9 JSON-outputting subcommands), reducing SKILL.md to a slim orchestrator. The user experience is identical.
- To revert at any time:
- ```bash
- ./install.sh --revert
- ```
- ---
- ## Plugin Structure
- ```
- atlas-session-lifecycle/
- .claude-plugin/
- plugin.json # Plugin metadata (name, version, keywords)
- skills/
- start/
- SKILL.md # Session lifecycle orchestrator
- stepback/
- SKILL.md # Strategic reassessment for stuck debugging
- scripts/
- session-init.py # Deterministic ops (9 JSON-outputting subcommands)
- custom.md # User customization hook (plain English)
- templates/
- CLAUDE-activeContext.md
- CLAUDE-decisions.md
- CLAUDE-mdReference.md
- CLAUDE-patterns.md
- CLAUDE-soul-purpose.md
- CLAUDE-troubleshooting.md
- v1/
- SKILL.md # v1 monolithic skill (867 lines)
- install.sh # Installer with version toggle and auto-update
- README.md
- LICENSE
- CONTRIBUTING.md
- CODE_OF_CONDUCT.md
- SECURITY.md
- ```
- ---
- ## Requirements
- - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
- - Python 3.8+
- - Git (optional -- enables `git mv` for tracked files during organization)
- ---
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
- ---
- ## License
- [MIT](LICENSE)
install.sh · Bundled script · 515 lines · 6 findings marked
- #!/usr/bin/env bash
- # ============================================================================
- # Atlas Session Lifecycle — Installer
- # ============================================================================
- # Usage:
- # curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 6 on GitHub
- # curl -fsSL ... | bash -s -- --plugin # install as Claude Code plugin
- # bash install.sh # skill mode (default)
- # bash install.sh --plugin # plugin mode
- # bash install.sh --version v1 # install v1 (legacy)
- # bash install.sh --revert # revert to v1
- # bash install.sh --update # pull latest and reinstall
- # bash install.sh --check-update # check for newer version
- # bash install.sh --no-extras # skip bundled extra skills
- # bash install.sh --all # install all extras without prompting
- # ============================================================================
- set -euo pipefail
- REPO_OWNER="anombyte93"
- REPO_NAME="atlas-session-lifecycle"
- SKILL_NAME="start"
- VERSION="4.1.0"
- # SECURITY: Pin to specific commit hash for integrity
- # Update this when releasing new versions
- PINNED_COMMIT="8c4cbc5"
- SKILL_DIR="${SKILL_DIR:-${HOME}/.claude/skills/${SKILL_NAME}}"
- PLUGIN_DIR="${HOME}/.claude/plugins/${REPO_NAME}"
- TEMPLATE_DIR="${HOME}/claude-session-init-templates"
- UPDATES_DIR="${HOME}/.config/claude-skills"
- UPDATES_FILE="${UPDATES_DIR}/updates.json"
- UPDATE_INTERVAL_SECONDS=86400
- GITHUB_API="https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest"
- CLONE_URL="https://github.com/${REPO_OWNER}/${REPO_NAME}.git"
- if [[ -t 1 ]] && [[ -z "${CI:-}" ]] && [[ -z "${NO_COLOR:-}" ]]; then
- RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[0;33m'
- CYAN='\033[0;36m'; BOLD='\033[1m'; RESET='\033[0m'
- else
- RED='' GREEN='' YELLOW='' CYAN='' BOLD='' RESET=''
- fi
- info() { printf "${CYAN}[info]${RESET} %s\n" "$*"; }
- ok() { printf "${GREEN}[ok]${RESET} %s\n" "$*"; }
- warn() { printf "${YELLOW}[warn]${RESET} %s\n" "$*"; }
- err() { printf "${RED}[error]${RESET} %s\n" "$*" >&2; }
- die() { err "$@"; exit 1; }
- cleanup() {
- if [[ -n "${TMPDIR_SKILL:-}" ]] && [[ -d "${TMPDIR_SKILL}" ]]; then
- rm -rf "${TMPDIR_SKILL}"
- fi
- }
- trap cleanup EXIT
- require_cmd() {
- command -v "$1" >/dev/null 2>&1 || die "Required command not found: $1"
- }
- check_update() {
- if [[ -n "${CI:-}" ]] || [[ -n "${NO_UPDATE_CHECK:-}" ]]; then return 0; fi
- require_cmd curl; require_cmd date; mkdir -p "${UPDATES_DIR}"
- if [[ -f "${UPDATES_FILE}" ]]; then
- local last_check; last_check=$(python3 -c "
- import json
- try:
- d = json.load(open('${UPDATES_FILE}'))
- print(d.get('skills', {}).get('${SKILL_NAME}', {}).get('last_check', 0))
- except: print(0)
- " 2>/dev/null || echo 0)
- local now; now=$(date +%s); local elapsed=$(( now - last_check ))
- if [[ ${elapsed} -lt ${UPDATE_INTERVAL_SECONDS} ]]; then
- local cached_latest; cached_latest=$(python3 -c "
- import json
- try:
- d = json.load(open('${UPDATES_FILE}'))
- print(d.get('skills', {}).get('${SKILL_NAME}', {}).get('latest', ''))
- except: print('')
- " 2>/dev/null || echo "")
- if [[ -n "${cached_latest}" ]] && [[ "${cached_latest}" != "${VERSION}" ]]; then
- warn "Update available: ${VERSION} -> ${cached_latest}"
- info "Run: curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash"
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 83 on GitHub
- fi; return 0
- fi
- fi
- local api_response; api_response=$(curl -fsSL --max-time 5 -H "Accept: application/vnd.github+json" "${GITHUB_API}" 2>/dev/null) || return 0
- local latest_version; latest_version=$(printf '%s' "${api_response}" | python3 -c "
- import json, sys, re
- try:
- data = json.load(sys.stdin)
- tag = data.get('tag_name', '')
- # SECURITY: Validate semver format to prevent code injection
- if re.match(r'^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$', tag):
- print(tag.lstrip('v'))
- else:
- print('')
- except: print('')
- " 2>/dev/null || echo "")
- if [[ -z "${latest_version}" ]]; then return 0; fi
- # SECURITY: Validate version format before use
- if [[ ! "${latest_version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then return 0; fi
- local now; now=$(date +%s)
- # SECURITY: Use shlex.quote equivalent via printf escaping
- python3 -c "
- import json, shlex
- path = shlex.quote('${UPDATES_FILE}')
- skill_name = shlex.quote('${SKILL_NAME}')
- now = ${now}
- latest = shlex.quote('${latest_version}')
- current = shlex.quote('${VERSION}')
- try: data = json.load(open(path))
- except: data = {}
- data.setdefault('skills', {})
- data['skills'][skill_name] = {'last_check': now, 'latest': latest, 'current': current}
- with open(path, 'w') as f: json.dump(data, f, indent=2)
- " 2>/dev/null || true
- if [[ "${latest_version}" != "${VERSION}" ]]; then
- warn "Update available: ${VERSION} -> ${latest_version}"
- info "Run: curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash"
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 120 on GitHub
- else ok "You are on the latest version (${VERSION})"; fi
- }
- revert_to_v1() {
- info "Reverting to v1 (monolithic SKILL.md, no script)"
- if [[ ! -d "${SKILL_DIR}" ]]; then
- die "No installation found at ${SKILL_DIR}. Nothing to revert."
- fi
- TMPDIR_SKILL=$(mktemp -d "${TMPDIR:-/tmp}/claude-skill-XXXXXX")
- info "Cloning ${REPO_OWNER}/${REPO_NAME} at ${PINNED_COMMIT}..."
- git clone --quiet "${CLONE_URL}" "${TMPDIR_SKILL}/repo" 2>/dev/null \
- || die "Failed to clone repository."
- git -C "${TMPDIR_SKILL}/repo" checkout --quiet "${PINNED_COMMIT}" 2>/dev/null \
- || die "Failed to checkout pinned commit."
- local src_dir="${TMPDIR_SKILL}/repo"
- if [[ ! -f "${src_dir}/v1/SKILL.md" ]]; then
- die "v1/SKILL.md not found in repository. Cannot revert."
- fi
- # Back up current v2 files
- if [[ -f "${SKILL_DIR}/SKILL.md" ]]; then
- cp "${SKILL_DIR}/SKILL.md" "${SKILL_DIR}/SKILL.md.v2-backup"
- ok "Backed up v2 SKILL.md -> SKILL.md.v2-backup"
- fi
- if [[ -f "${SKILL_DIR}/session-init.py" ]]; then
- cp "${SKILL_DIR}/session-init.py" "${SKILL_DIR}/session-init.py.v2-backup"
- ok "Backed up session-init.py -> session-init.py.v2-backup"
- fi
- # Install v1 SKILL.md
- cp "${src_dir}/v1/SKILL.md" "${SKILL_DIR}/SKILL.md"
- ok "Installed v1 SKILL.md (monolithic)"
- # Remove session-init.py (v1 doesn't use it)
- if [[ -f "${SKILL_DIR}/session-init.py" ]]; then
- rm "${SKILL_DIR}/session-init.py"
- ok "Removed session-init.py (not used by v1)"
- fi
- local timestamp; timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
- cat > "${SKILL_DIR}/.version" <<VEOF
- ${VERSION}-v1
- installed: ${timestamp}
- mode: revert
- repo: ${REPO_OWNER}/${REPO_NAME}
- skill_version: v1
- VEOF
- ok "Wrote .version (${VERSION}-v1, ${timestamp})"
- printf "\n"
- printf "${GREEN}${BOLD}Successfully reverted to v1${RESET}\n"
- printf " Location: %s\n" "${SKILL_DIR}"
- printf " Note: v2 files backed up with .v2-backup extension\n"
- printf "\n"
- }
- install_plugin() {
- local mode="install"
- info "Atlas Session Lifecycle — Plugin Installer"
- info "Version: ${BOLD}v${VERSION}${RESET}"
- printf "\n"; require_cmd git
- if [[ -d "${PLUGIN_DIR}" ]]; then
- mode="upgrade"
- info "Existing plugin installation detected"
- info "Mode: upgrade (pulling latest)"
- cd "${PLUGIN_DIR}"
- git fetch --quiet origin main 2>/dev/null || true
- git reset --hard origin/main --quiet 2>/dev/null || {
- warn "Git pull failed, doing fresh clone"
- cd "${HOME}"
- rm -rf "${PLUGIN_DIR}"
- mode="install"
- }
- if [[ "${mode}" == "upgrade" ]]; then
- local timestamp; timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
- ok "Updated plugin to latest (${timestamp})"
- printf "\n"
- printf "${GREEN}${BOLD}Successfully upgraded atlas-session-lifecycle plugin${RESET}\n"
- printf " Location: %s\n" "${PLUGIN_DIR}"
- printf "\n"
- info "To use: ${CYAN}/start${RESET}"
- printf "\n"
- return 0
- fi
- fi
- if [[ "${mode}" == "install" ]]; then
- info "Mode: fresh install"
- mkdir -p "$(dirname "${PLUGIN_DIR}")"
- git clone --quiet "${CLONE_URL}" "${PLUGIN_DIR}" 2>/dev/null \
- || die "Failed to clone repository."
- ok "Cloned plugin to ${PLUGIN_DIR}"
- fi
- # Also install templates to home dir fallback
- if [[ -d "${PLUGIN_DIR}/templates" ]]; then
- mkdir -p "${TEMPLATE_DIR}"
- cp "${PLUGIN_DIR}/templates/"* "${TEMPLATE_DIR}/" 2>/dev/null || true
- ok "Installed templates to ${TEMPLATE_DIR}/ (fallback)"
- fi
- printf "\n"
- printf "${GREEN}${BOLD}Successfully installed atlas-session-lifecycle plugin${RESET}\n"
- printf " Location: %s\n" "${PLUGIN_DIR}"
- printf " Templates: %s\n" "${TEMPLATE_DIR}"
- printf "\n"
- info "To use: ${CYAN}/start${RESET}"
- printf "\n"
- }
- install_extra_skills() {
- # Discover and install bundled skills beyond /start
- # $1 = src_dir (cloned repo), $2 = "all"|"ask"|"none"
- local src_dir="$1"
- local extras_mode="${2:-ask}"
- local skills_base="${HOME}/.claude/skills"
- if [[ "${extras_mode}" == "none" ]]; then return 0; fi
- # Discover extra skills (everything in skills/ except start/)
- local extras=()
- local descriptions=()
- if [[ -d "${src_dir}/skills" ]]; then
- for skill_dir in "${src_dir}/skills"/*/; do
- local skill_name; skill_name=$(basename "${skill_dir}")
- if [[ "${skill_name}" == "start" ]]; then continue; fi
- if [[ -f "${skill_dir}/SKILL.md" ]]; then
- extras+=("${skill_name}")
- # Extract description from YAML frontmatter
- local desc; desc=$(sed -n 's/^description: *"\{0,1\}\(.*\)"\{0,1\}$/\1/p' "${skill_dir}/SKILL.md" | head -1)
- descriptions+=("${desc:-No description}")
- fi
- done
- fi
- if [[ ${#extras[@]} -eq 0 ]]; then return 0; fi
- printf "\n"
- info "Bundled extra skills available:"
- printf "\n"
- for i in "${!extras[@]}"; do
- printf " ${BOLD}%d)${RESET} ${CYAN}/%s${RESET}\n" "$((i+1))" "${extras[$i]}"
- printf " %s\n" "${descriptions[$i]:0:100}"
- done
- printf "\n"
- local install_extras=()
- if [[ "${extras_mode}" == "all" ]]; then
- install_extras=("${extras[@]}")
- info "Installing all extra skills (--all)"
- elif [[ -t 0 ]] && [[ -t 1 ]]; then
- # Interactive — ask the user
- printf "Install extra skills? [${BOLD}a${RESET}]ll / [${BOLD}n${RESET}]one / [${BOLD}s${RESET}]elect: "
- local choice; read -r choice
- case "${choice}" in
- a|A|all|ALL|"")
- install_extras=("${extras[@]}") ;;
- n|N|none|NONE)
- info "Skipping extra skills"
- return 0 ;;
- s|S|select|SELECT)
- for i in "${!extras[@]}"; do
- printf " Install ${CYAN}/%s${RESET}? [Y/n]: " "${extras[$i]}"
- local yn; read -r yn
- case "${yn}" in
- n|N|no|NO) ;;
- *) install_extras+=("${extras[$i]}") ;;
- esac
- done ;;
- *)
- info "Skipping extra skills"
- return 0 ;;
- esac
- else
- # Non-interactive (piped via curl) — install all by default
- install_extras=("${extras[@]}")
- info "Installing all extra skills (non-interactive)"
- fi
- # Install selected extras
- for skill_name in "${install_extras[@]}"; do
- local target="${skills_base}/${skill_name}"
- mkdir -p "${target}"
- cp "${src_dir}/skills/${skill_name}/SKILL.md" "${target}/SKILL.md"
- ok "Installed /${skill_name} to ${target}/"
- done
- if [[ ${#install_extras[@]} -gt 0 ]]; then
- printf "\n"
- ok "Installed ${#install_extras[@]} extra skill(s)"
- fi
- }
- install_skill() {
- local target_version="${1:-v2}"
- local extras_mode="${2:-ask}"
- local mode="install"
- info "Atlas Session Lifecycle — Skill Installer"
- info "Skill: ${BOLD}${SKILL_NAME}${RESET} v${VERSION} (${target_version})"
- printf "\n"; require_cmd git
- if [[ -d "${SKILL_DIR}" ]]; then
- mode="upgrade"
- local existing_version="unknown"
- if [[ -f "${SKILL_DIR}/.version" ]]; then
- existing_version=$(head -1 "${SKILL_DIR}/.version" 2>/dev/null || echo "unknown")
- fi
- info "Existing installation detected (${existing_version})"
- info "Mode: upgrade"
- if [[ -f "${SKILL_DIR}/SKILL.md" ]]; then
- cp "${SKILL_DIR}/SKILL.md" "${SKILL_DIR}/SKILL.md.bak"
- ok "Backed up SKILL.md -> SKILL.md.bak"
- fi
- else info "Mode: fresh install"; fi
- TMPDIR_SKILL=$(mktemp -d "${TMPDIR:-/tmp}/claude-skill-XXXXXX")
- info "Cloning ${REPO_OWNER}/${REPO_NAME} at ${PINNED_COMMIT}..."
- git clone --quiet "${CLONE_URL}" "${TMPDIR_SKILL}/repo" 2>/dev/null \
- || die "Failed to clone repository."
- git -C "${TMPDIR_SKILL}/repo" checkout --quiet "${PINNED_COMMIT}" 2>/dev/null \
- || die "Failed to checkout pinned commit."
- local src_dir="${TMPDIR_SKILL}/repo"
- mkdir -p "${SKILL_DIR}"
- if [[ "${target_version}" == "v1" ]]; then
- # v1 install: monolithic SKILL.md, no script
- if [[ -f "${src_dir}/v1/SKILL.md" ]]; then
- cp "${src_dir}/v1/SKILL.md" "${SKILL_DIR}/SKILL.md"
- ok "Installed v1 SKILL.md (monolithic)"
- else
- die "v1/SKILL.md not found in repository."
- fi
- if [[ -f "${SKILL_DIR}/session-init.py" ]]; then
- rm "${SKILL_DIR}/session-init.py"
- ok "Removed session-init.py (not used by v1)"
- fi
- else
- # v2 install: skill from skills/start/, script from scripts/
- if [[ -f "${src_dir}/skills/start/SKILL.md" ]]; then
- cp "${src_dir}/skills/start/SKILL.md" "${SKILL_DIR}/SKILL.md"
- ok "Installed SKILL.md (orchestrator)"
- else
- die "skills/start/SKILL.md not found in repository."
- fi
- if [[ -f "${src_dir}/scripts/session-init.py" ]]; then
- cp "${src_dir}/scripts/session-init.py" "${SKILL_DIR}/session-init.py"
- chmod +x "${SKILL_DIR}/session-init.py"
- ok "Installed session-init.py (backend)"
- else
- die "scripts/session-init.py not found in repository."
- fi
- # Deploy MCP server source (atlas-session MCP package)
- if [[ -d "${src_dir}/src/atlas_session" ]]; then
- mkdir -p "${SKILL_DIR}/src"
- rm -rf "${SKILL_DIR}/src/atlas_session"
- cp -r "${src_dir}/src/atlas_session" "${SKILL_DIR}/src/atlas_session"
- if [[ -f "${src_dir}/src/pyproject.toml" ]]; then
- cp "${src_dir}/src/pyproject.toml" "${SKILL_DIR}/src/pyproject.toml"
- fi
- ok "Installed MCP server (src/atlas_session/)"
- else
- warn "src/atlas_session/ not found — MCP server not installed"
- fi
- fi
- # Install templates
- if [[ -d "${src_dir}/templates" ]]; then
- mkdir -p "${TEMPLATE_DIR}"
- cp "${src_dir}/templates/"* "${TEMPLATE_DIR}/" 2>/dev/null || true
- ok "Installed templates to ${TEMPLATE_DIR}/"
- fi
- if [[ -f "${src_dir}/install.sh" ]]; then
- cp "${src_dir}/install.sh" "${SKILL_DIR}/install.sh"
- chmod +x "${SKILL_DIR}/install.sh"
- fi
- # Offer extra bundled skills (v2 only)
- if [[ "${target_version}" == "v2" ]]; then
- install_extra_skills "${src_dir}" "${extras_mode}"
- fi
- local timestamp; timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
- cat > "${SKILL_DIR}/.version" <<VEOF
- ${VERSION}
- installed: ${timestamp}
- mode: ${mode}
- repo: ${REPO_OWNER}/${REPO_NAME}
- skill_version: ${target_version}
- VEOF
- ok "Wrote .version (${VERSION}, ${timestamp})"
- # Clean up old flat file if it exists
- if [[ -f "${HOME}/.claude/skills/start.md" ]]; then
- rm "${HOME}/.claude/skills/start.md"
- ok "Removed old flat file start.md"
- fi
- printf "\n"
- printf "${GREEN}${BOLD}Successfully %s ${SKILL_NAME} v${VERSION} (${target_version})${RESET}\n" \
- "$([ "${mode}" = "upgrade" ] && echo "upgraded" || echo "installed")"
- printf " Location: %s\n" "${SKILL_DIR}"
- printf " Templates: %s\n" "${TEMPLATE_DIR}"
- if [[ "${target_version}" == "v2" ]]; then
- printf " Script: %s/session-init.py\n" "${SKILL_DIR}"
- fi
- printf "\n"
- info "To use: ${CYAN}/start${RESET}"
- printf "\n"
- }
- main() {
- local target_version="v2"
- local install_mode="skill"
- local extras_mode="ask"
- # Parse modifier flags first
- local args=()
- for arg in "$@"; do
- case "${arg}" in
- --plugin) install_mode="plugin" ;;
- --no-extras) extras_mode="none" ;;
- --all) extras_mode="all" ;;
- *) args+=("${arg}") ;;
- esac
- done
- case "${args[0]:-}" in
- --check-update|-u) check_update ;;
- -v) echo "atlas-session-lifecycle v${VERSION}" ;;
- --revert) revert_to_v1 ;;
- --update)
- info "Updating atlas-session-lifecycle..."
- if [[ "${install_mode}" == "plugin" ]]; then
- install_plugin
- else
- install_skill "v2" "${extras_mode}"
- fi
- ;;
- --help|-h)
- printf "Usage: %s [OPTIONS]\n" "${0##*/}"
- printf "\n${BOLD}Atlas Session Lifecycle${RESET} — Session lifecycle management for Claude Code\n"
- printf "\nInstall modes:\n"
- printf " (no args) Install as skill to ~/.claude/skills/start/\n"
- printf " --plugin Install as plugin to ~/.claude/plugins/\n"
- printf "\nOptions:\n"
- printf " --version v1|v2 Install specific version (skill mode only)\n"
- printf " --revert Revert from v2 to v1 (skill mode only)\n"
- printf " --update Pull latest and reinstall\n"
- printf " --check-update Check for newer release\n"
- printf " --all Install all bundled skills without prompting\n"
- printf " --no-extras Skip bundled extra skills (only install /start)\n"
- printf " -v Print version\n"
- printf " --help Show help\n"
- printf "\nExamples:\n"
- printf " # One-liner install (skill mode)\n"
- printf " curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash\n"
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 491 on GitHub
- printf "\n # One-liner install (plugin mode)\n"
- printf " curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash -s -- --plugin\n"
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 493 on GitHub
- printf "\n # Update existing installation\n"
- printf " curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash -s -- --update\n" ;;
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 495 on GitHub
- "")
- if [[ "${install_mode}" == "plugin" ]]; then
- install_plugin
- else
- install_skill "v2" "${extras_mode}"
- fi
- check_update ;;
- --version)
- target_version="${args[1]:-v2}"
- if [[ "${target_version}" != "v1" ]] && [[ "${target_version}" != "v2" ]]; then
- die "Invalid version: ${target_version}. Use v1 or v2."
- fi
- install_skill "${target_version}" "${extras_mode}"
- check_update ;;
- *)
- die "Unknown argument: ${args[0]} (try --help)" ;;
- esac
- }
- main "$@"
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.