Install

Audience: project maintainers and authorized agents configuring an installation. For the everyday workflow, start with Quickstart.

Install the claude-foundation CLI once on your machine, then initialize Change Loop in each project. Running init again upgrades the managed files. It is safe for brownfield repositories: it seeds what is missing, refreshes what it owns, and leaves project-owned files alone.

Requirements and recommended tools

Tool	Status	Why
Node.js 20.19 or later	Required	The runtime is plain ESM Node with no compile step
OpenSpec CLI 1.7.0	Required	Spec synchronization and archive
Git	Recommended	Enables worktree isolation; a dirty or non-Git project falls back to an isolated copy

npm install -g @fission-ai/openspec@1.7.0

jq is recommended for merging hooks into an existing .claude/settings.json. Without it, installation continues, preserves the existing file, and writes .claude/settings.foundation.json for manual review.

Install from source

git clone https://github.com/Maximumsoft-Co-LTD/claude-foundation.git
cd claude-foundation
./install.sh /path/to/your-project

Install with Homebrew

brew tap maximumsoft-co-ltd/claude-foundation \
  https://github.com/Maximumsoft-Co-LTD/claude-foundation
brew install claude-foundation
claude-foundation init /path/to/your-project --yes

claude-foundation init is the same installer; --yes skips the confirmation prompt. Later upgrades use brew upgrade claude-foundation, followed by init for each project you want to refresh.

Tip

Open a new agent session in the target project after installing, so the slash commands are registered.

Other agent hosts

Claude Code needs no adapter. For other hosts, --host layers one over the same shared install:

claude-foundation init /path/to/your-project --host cursor    # or opencode, codex

Host	What the adapter adds
Cursor	Seven primary lifecycle prompts including optional /deliver, plus /changes and the /feature compatibility alias in .cursor/commands/, and the always-on skill router as a .mdc rule with alwaysApply: true
OpenCode	The same seven primary prompts plus two utility/alias prompts in .opencode/commands/, and a guard plugin at .opencode/plugins/foundation.js that replays the shipped hooks — the secrets and phase-mutation guards block live, lint feeds back on edit. Skills and the agent contract need no adapter: OpenCode reads .claude/skills/ and AGENTS.md natively
Codex CLI	The nine prompts in $CODEX_HOME/prompts (Codex has no per-project prompt directory), stamped with an ownership marker so re-installs refresh Change Loop prompts without clobbering a same-named user prompt

Codex has no tool hooks

Codex cannot run live guards, so the secrets and phase-mutation hooks are inert there. Land gates and the opt-in no-direct-main-commit.sh remain the enforcement.

Verify

claude-foundation version
claude-foundation doctor --stage change

doctor is the readiness check you should reach for whenever something looks wrong. It diagnoses project, provider, and lifecycle state, and it reports unresolved apply transactions before Land ever reaches them.

Commit the installation

In a Git project, the installer stages the managed setup files but does not commit them. Review and commit that setup before the first change:

git status
git commit -m "chore: install Change Loop"

This needs your explicit approval. If the files remain uncommitted, Change Loop correctly treats them as part of the next change surface, which makes the first change larger and forces copied-workspace isolation.

Start your first change

Open a new agent session in the initialized project and describe the outcome:

/change allow account owners to edit their display name

Review the proposed agreement, then continue with /build, /prove, and explicit /land. The agent runs the underlying CLI and recovery commands. See the Quickstart for the complete user journey.

Advanced setup

Only needed for locked-down or unattended (CI) environments. You can skip this section for a normal interactive setup.

Permission allowlist

.claude/settings.json stays project-owned. The installer merges the shipped hooks and appends a narrow permissions.allow list, so Claude Code does not ask for approval on every harness step: Bash(claude-foundation *), Bash(.foundation/bin/claude-foundation *), Bash(node .claude/harness/foundation.mjs *), Edit(/.foundation/sandboxes/**), Edit(/.foundation/repository-sandboxes/**), Edit(/.foundation/drafts/**) (the Change draft), and Edit(/openspec/investigations/**) (the Investigate record). Project test runners get no rule: each Build task returns its verify as a checkCommand (claude-foundation exec <change> --task <id> -- <verify>) that the CLI rule already covers. It adds only missing rules after your own, never removes or reorders entries, and a rerun adds nothing. The PreToolUse guards still run before these rules. Pass --no-permission-allowlist on every install or upgrade to leave permissions.allow untouched.

Headless / CI (claude -p)

Claude Code ignores project permissions.allow entries until the workspace is trusted. In a fresh checkout, a headless claude -p run prints Ignoring ... permissions.allow entry ... this workspace has not been trusted, so the installed Bash(claude-foundation *) rule does nothing and every harness call is denied. Either run claude once interactively in the project and accept the trust prompt, or grant exactly the installed allowlist on each headless run (an Edit rule also covers Write; edits elsewhere in the project stay denied):

claude -p "/change <intent>" --allowedTools \
  "Bash(claude-foundation *)" "Bash(.foundation/bin/claude-foundation *)" \
  "Bash(node .claude/harness/foundation.mjs *)" "Edit(/.foundation/drafts/**)" \
  "Edit(/.foundation/sandboxes/**)" "Edit(/.foundation/repository-sandboxes/**)" \
  "Edit(/openspec/investigations/**)"

Build checks run through claude-foundation exec, so test runners need no grant; add other project tools only when a run needs them. Claude Code treats paths under ~/.claude/ as sensitive, so keep consumer projects outside that directory for unattended runs.

What the installer owns

This boundary matters, because upgrades act on it. Change Loop-managed paths are copied on every install and recorded in .foundation/install-manifest.txt:

.claude/orchestrator.md
.claude/commands
.claude/harness
.claude/skills
.claude/rules
.claude/hooks
openspec/schemas
.foundation/.gitignore
.foundation/README.md
WORKFLOW.md

Project-owned paths are seeded or merged but never clobbered:

.claude/settings.json          # hooks merged with jq; timestamped backup
openspec/config.yaml           # copied only when missing
openspec/repositories.yaml     # copied only when missing
foundation.json                # seeded; supported missing-field/default migrations
CLAUDE.md / AGENTS.md          # only the marked pointer block is rewritten

Your specs, active changes, runtime state, custom agents, and hooks survive every upgrade. A path dropped from the managed list is removed from your project only if the manifest previously claimed it — so Change Loop never deletes a file it did not install.

Because foundation.json belongs to your project, an upgrade preserves custom policy rather than replacing the file wholesale. It can add missing fields and migrate recognized historical default budgets. Read Configure foundation.json before changing it.

Project-owned does not mean the user must edit the file personally; an authorized agent can configure it. Installed system instructions are separate from project preferences. See files and ownership.

Browser proof stays yours

Change Loop does not install test frameworks, browsers, or project dependencies. If a claim needs browser evidence, install and lock @playwright/test and its browser binaries in your application. Change Loop validates and executes the local tool; it will never download an unpinned browser framework during proof.

The same rule applies everywhere: every executable named by an adapter is owned and version-locked by your repository, not by the harness.