Install and set up

Requirements

macOS or Linux (on Windows, use WSL).
Node.js 22.14 or later.
A git repository with at least one commit and a remote (normally origin).

Run init

In the repository, in your own terminal:

npx @align-agent/cli init

Running it again is safe. In order, it:

Checks the repository: a git work tree with a recognised remote and a root commit.
Installs itself for your user: the CLI goes into ~/.align/lib, and a small launcher into ~/.align/bin/align that your hooks call.
Signs you in: it prints a short code and opens your browser (on a terminal) at the sign-in page; enter the code there. In the browser you pick your organisation, or create a new one. If you are already signed in, it reuses that.
Connects the repository to your organisation. The first person on a repository connects it; if it belongs to another organisation, init says so, offers the join link when you collaborate on it on GitHub (auto-join), and installs nothing.
Asks you to opt in, after showing what is captured and what never is. For an organisation in the beta it also links the pilot data terms you accept by opting in. Saying no installs nothing and captures nothing.
Sets up each agent you use (it detects Claude Code, Cursor and Codex, and asks for each): see below.
Installs two git hooks, prepare-commit-msg and post-commit. An existing hook is kept and still runs after ALIGN's part, and its exit code wins. If your repository uses core.hooksPath, init leaves it alone and prints the lines to add there.
Offers a backfill: with your agreement it reads your recent sessions in this repository (30 days on the Free plan, 90 on the others) to find the decisions already in them. Inside an agent's shell it asks you to run align backfill in your own terminal instead.
Prints a summary. Nothing is confirmed: ALIGN never confirms a decision for you. Next is align confirm (Proposals and confirming).

Files it writes inside the repository are added to .git/info/exclude, so git status stays clean.

Options

Option	Effect
`--harness claude-code,cursor,codex`	set up only these agents
`-y`, `--yes`	accept the defaults without asking (opting in included)
`--no-backfill`	skip reading recent sessions
`--days <n>`	how many days of history to read, 1 to 90
`--org <slug>`	the organisation to use
`--remote <name>`	the git remote that identifies this repository
`--accept-pilot-terms`	accept a beta organisation's pilot data terms (with `--yes`)
`--server <url>`	the server to use (https)

Without a terminal, --yes is required to opt in. Every command is in the CLI reference.

Claude Code

Hooks (session start, prompt, stop and session end) are merged into the repository's .claude/settings.local.json. A committed or invalid settings file is left unchanged, and init says so.
Packs: each session starts with the decisions that apply to the files you work on (Packs and MCP tools).
/align shows those decisions in a session (~/.claude/commands/align.md).
MCP: registered with claude mcp add --scope local. If claude is not on your PATH, init prints the command to run.
The plugin: if the ALIGN Claude Code plugin is enabled, it brings the hooks, the MCP server and its commands itself, and init adds nothing for Claude Code. align doctor offers to remove hooks added before the plugin.

Cursor

Hooks are merged into ~/.cursor/hooks.json (a backup is kept once). They do nothing outside opted-in repositories.
A rule file, .cursor/rules/align.mdc, always applied, carries the pack and is refreshed with it.
MCP goes into ~/.cursor/mcp.json, or into the repository's .cursor/mcp.json when that file exists and is not committed.
Permission for the read-only tools: get_context, get_decision, search_decisions, list_open_questions and get_contract are added to permissions.allow in the repository's .cursor/cli.json (when that file is not committed), so Cursor's agent can call them without asking, also in print mode (agent -p). record_decision and ask_owner are not added: Cursor still asks before those.

Codex

Hooks are merged into ~/.codex/hooks.json (or $CODEX_HOME/hooks.json). Run /hooks once in Codex and trust the ALIGN hooks.
MCP is added with codex mcp add, or as an [mcp_servers.align] table in Codex's config.toml.

Other MCP agents

Any agent that starts MCP servers over stdio can use the same server. Print its configuration:

align mcp --print-config gemini     # also: hermes, openclaw, generic

For an agent that runs somewhere else (not on your laptop), see Remote MCP and OAuth.

Turning it off

align off              # stop capturing this repository at once (unsent data here is deleted)
align on               # opt in again
align uninstall        # remove what was added for this repository
align uninstall --purge --yes   # also sign out and delete everything kept on this laptop

align status shows what is captured here and where it goes. If something does not work, see Troubleshooting.