Skip to content

INSTALL.md

Latest commit

 

History

History
171 lines (148 loc) · 9.57 KB

INSTALL.md

File metadata and controls

171 lines (148 loc) · 9.57 KB
Raw

Install wizard (agent-facing)

You are Claude Code, running this install for the user. Follow these steps as an interactive wizard. Detect what's already present, ask before installing anything optional or heavy, never overwrite without a backup, and keep questions to a minimum — skip anything already satisfied. SRC below is the directory you cloned this repo into.

Step 0 — Detect (don't install anything yet)

Run these and show the user a short status summary:

claude --version
ls -d ~/.claude/skills/gstack 2>/dev/null && echo "gstack: present" || echo "gstack: missing"
command -v codex >/dev/null && { command -v gtimeout || command -v timeout; } >/dev/null && command -v pgrep >/dev/null && codex exec --help 2>/dev/null | grep -q -- --ephemeral && printf '0.159.0\n%s\n' "$(codex --version | awk '{print $2}')" | sort -V -C && echo "codex gate: ready" || echo "codex gate: needs codex-cli 0.159.0+ + GNU timeout + pgrep (macOS: brew install coreutils)"
test -f ~/.claude/CLAUDE.md && echo "CLAUDE.md: exists" || echo "CLAUDE.md: none"
  • If the codex gate line reports missing: install or upgrade codex-cli (0.159.0+, the first with gpt-6.1-sol) + GNU timeout (macOS: brew install coreutils) — the codex gate does not run without them.

Step 1 — Ask what to set up (AskUserQuestion)

Offer only items that are missing or are real decisions. The core kit (skills + agents + the stack-update check — enables the default background-subagent + Workflows path) is always installed: it's the point of running this installer, not a choice, and install.sh has no flag to skip it — so don't offer it as a deselectable option. Suggested:

  1. Optional add-ons: gstack (if missing).

  2. CLAUDE.md handling — only if ~/.claude/CLAUDE.md already exists: append the feature-workflow pointer section (recommended — the workflow itself lives in the feature-workflow skill the core kit installs) / replace with this repo's CLAUDE.md / leave mine untouched. If none exists, just install this repo's CLAUDE.md (no need to ask).

  3. Opus version — only if ANTHROPIC_DEFAULT_OPUS_MODEL isn't already in their settings env: ask which Opus the opus alias should mean (via AskUserQuestion). Options:

    • don't pin (recommended, the repo default — the alias follows whatever Anthropic ships as Opus)
    • claude-opus-5-5 (pinned, so a future Opus release won't change or re-price agent files saying model: opus until you move it)
    • custom: any full model ID the user types (the "Other" answer)

  4. Codex review model — only if CODEX_REVIEW_MODEL isn't already in their settings env: ask which model the codex cross-review gate (the always-on push gate) uses. All three run at medium reasoning effort. Options:

    • gpt-6.1-sol (recommended, the repo default — OpenAI's current workhorse, 272k context)
    • gpt-6-astra (most capable, 272k context — slower per run)
    • gpt-6-luna (fast and affordable, 272k context)

    Tell them this sticks: install.sh never clobbers an existing value, so changing it later means editing ~/.claude/settings.json by hand.

  5. Master model — always ask: the master is the session they open, which plans and coordinates. First show their current model and modelSettings.claude-opus-5-5.effortLevel from ~/.claude/settings.json ("not set" where absent). Options:

    • Opus 5.5 at xhigh (recommended)
    • keep current, ask next time
    • don't ask again (keeps current; /stack-update stops asking until the recommendation changes)
    • other: the user types MODEL_ID or MODEL_ID:EFFORT (effort is one of low, medium, high, xhigh; max can't be saved as a default)

Explain briefly: the default path (background subagents + Workflows) needs nothing beyond the skill + agents — no flags, no extra tools. gstack is optional — it powers /browse, the workflow's browser verification; without it, use another browser tool.

Step 2 — Execute (only chosen + only missing)

Core kit + settings + CLAUDE.md — all of it is install.sh's job; don't reimplement any of its copy/backup/prune/merge logic here. Its settings merge setdefaults CLAUDE_CODE_ENABLE_TODO_TOOLS (the task-list feature) along with every other key in settings.example.json's env block — added only if that key isn't already set, never clobbering your existing value. Translate the Step 1 answers into flags and run it once:

  • Opus answer was don't pin, or the question was skipped because a pin already exists → pass no --opus-pin (an existing value is never clobbered, except the kit's earlier claude-opus-5 pin, which is removed).

  • Opus answer was claude-opus-5-5 or a custom ID → --opus-pin=<that id>.

  • ~/.claude/CLAUDE.md didn't exist → pass no --claude-md flag (the default installs it).

  • CLAUDE.md handling was append → --claude-md=append.

  • CLAUDE.md handling was replace → --claude-md=replace.

  • CLAUDE.md handling was leave mine untouched → --claude-md=leave.

  • Codex review model answer was gpt-6.1-sol → --codex-model=gpt-6.1-sol.

  • Codex review model answer was gpt-6-astra → --codex-model=gpt-6-astra.

  • Codex review model answer was gpt-6-luna → --codex-model=gpt-6-luna.

  • The question was skipped because CODEX_REVIEW_MODEL already exists → pass no --codex-model flag (the existing value is never clobbered, except the kit's earlier gpt-5.6-sol / gpt-6-sol / gpt-5.6-luna, which move to gpt-6.1-sol / gpt-6.1-sol / gpt-6-luna).

  • Master model answer was Opus 5.5 at xhigh → --master=recommended.

  • Master model answer was keep current, ask next time → --master=keep.

  • Master model answer was don't ask again → --master=dont-ask.

  • Master model answer was a typed MODEL_ID[:EFFORT] → --master=<what they typed>.

Every codex-model answer passes its own explicit flag, including the recommended one — there is no "recommended → pass no flag" branch, so the install command line always records which model was actually chosen.

For example, a user who wants to append the Feature workflow section to their existing CLAUDE.md:

"$SRC/install.sh" --claude-md=append

Run it and show the output — it reports what it backed up, installed, pruned, and merged (skills, agents, rules, the update-check, session-name, skill-reload and subagent-no-background hooks and the update stamp, retired-agent removal, and the settings.json merge). If it exits non-zero, stop — report exactly what it printed; nothing after that point in its output was applied.

gstack (if chosen):

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack \
  && cd ~/.claude/skills/gstack && ./setup

Step 3 — Tell the user the manual steps

Default path: just restart Claude Code so the skill + agents load. Nothing else. Then suggest a test (background subagents, read-only → no worktrees):

Spawn 3 background subagents to review this code in parallel — one on security, one on performance, one on test coverage. Have them report findings.

Also mention: a SessionStart hook now checks once a day for a newer claude-code-setup and shows one line at every session start while there's an update — /stack-update applies it, and nothing is written without approval. Opt out with touch ~/.claude/.claude-code-setup/disabled. Unless you are answering in English, write ~/.claude/.claude-code-setup/notice as /stack-update step 7 describes, so that line is in the user's language. A second SessionStart hook names the session from a Session name: <project>-<role> line in the repo's CLAUDE.md, so sessions in a project's sibling repos (an app, its API, a web client — any number) can find and message each other; tell the user to add this block to each sibling repo's CLAUDE.md, or let Claude propose it the first time a feature spans repos:

## Sibling repos
Session name: acme-ios
- acme-api (acme/api): the REST API this app consumes
- acme-web (acme/web): shares the API client types

A SessionStart hook with matcher compact reminds the session to invoke the feature-workflow skill again after a compaction when it had loaded it before. A PreToolUse hook on Bash (matcher Bash|Monitor, so Monitor calls pass) denies run_in_background inside subagents (their background commands would outlive them) and any poll loop on a .output.done marker (never written), and BASH_DEFAULT_TIMEOUT_MS is set to 15 minutes so a build or test run in the main session with no explicit timeout is not auto-backgrounded at 2 minutes (a subagent's command is moved at 3 minutes whatever the timeout), and bashOutputMaxChars to 30000 so a valid command result over 30k characters arrives as a file path plus a 2k preview instead of flooding the context, and bashEditDiffEnabled to true so the transcript records which files each Bash command changed (/analyze-arcs reads it). The master model is whatever they answered in Step 1 — install.sh writes model / modelSettings only for Opus 5.5 at xhigh or a typed model, and warns if ANTHROPIC_MODEL is set, since that outranks the settings model. Hooks are read at session start: the new hook takes effect in the next session, or after reviewing it in /hooks.

Rules

  • Never overwrite ~/.claude/CLAUDE.md or settings.json without a backup.
  • Skip anything already installed — say "already present" and move on.
  • Report a final summary: what was installed, what was skipped, what's manual.