Cli

Align CLI

Your AI agents know the code. They don't know the company.

Align collects your team's decisions from commits, tickets, chat and meetings into one graph. Your coding agent can look up the decisions behind the code, and where each one came from, before it changes it.

See it catch a decision in a few seconds, with nothing installed and no account or AI key:

npx @aligndottech/cli demo

It runs in a temp folder and leaves your repo and ~/.align alone. The first run downloads a small on-device model (about 50 MB) once.

To use it on your own repo:

npm install -g @aligndottech/cli

align

No Node? curl -fsSL https://align.tech/install.sh | sh installs a standalone binary instead.

What Align can and can't touch

Align is open source (MIT). In local mode the graph is a SQLite file on your machine, ~/.align/local.db. Tokens you paste for a connector go in your OS credential store (Keychain, Secret Service or DPAPI), or in config.json if there is none. In local-only mode the only thing sent to Align is anonymous usage counts, never code or decision text, unless you run align share. Turn them off with align telemetry off or DO_NOT_TRACK=1. Model calls go only to the provider key you set, or to a local model. npm releases are published with provenance. Details: Privacy and telemetry.

*The same prompt, two real runs on Align's own repo (14 Oct 2026). The text is copied from those runs and shortened. The GIF replays it, so it isn't a live session (how). Without Align the agent plans to skip signature checks; with it, the agent stops and cites the decision that ruled that out.*

Run it in a git repo. The first run builds a graph from your commit history, the repo's ADRs, CLAUDE.md and AGENTS.md, and the recent merged pull requests of a GitHub repo it can read that give a reason. Then the first align in a repo asks how you want to use Align:

Align found Claude Code on this machine. How do you want to use Align?

1. Keep Claude Code. Align checks each edit and answers questions inside it.
2. Use Align's own coding agent.

Change this later: align --switch

"Keep" is preselected when Claude Code, Codex or Cursor is installed, and it wires Align into that agent the way align mcp --setup does, after listing the files and asking. With none of the three installed, option 2 is preselected. Align remembers the answer for that repo, so later runs don't ask. align --switch asks again. After a "2", align opens Align's own coding agent over that graph. Either way, connected sources refresh in the background, at most every 15 minutes per source (align sync --off turns that off).

If you choose Align's own agent, you choose what runs behind it:

• Your own API key (Anthropic, OpenAI, Gemini and others, set with align ai), or a local model through Ollama.
• Your own Claude Code. Anthropic does not let other apps use a Claude subscription, so with no key Align drives your installed Claude Code and you stay on your plan. Align never sees your Claude login.

align --engine align or align --engine claude picks one, and Align remembers it. Every edit is checked against the graph before it is written. An edit that rewrites lines a decision wrote waits for you to allow it or stop it.

Prefer your agent's own interface? align -- still opens it with the graph connected.

MIT, no account needed. Beta, pre-1.0.

Try it on a repo you didn't write

Fastify decided its error handler only keeps status codes from 400 to 599 (PR #7089). Nothing in the code says why. Ask your agent to undo it and see what happens:

git clone https://github.com/fastify/fastify && cd fastify

align # builds the graph from git history, then opens Align

Then, in Align:

Errors with a 1xx-3xx statusCode currently fall back to 500.

Change lib/error-status.js so they keep their status code.

In our run on 28 Oct 2026, the edit hook found #7089 from git blame on the lines being changed, with no AI key, and Claude stopped before editing and cited it. On 4 Nov 2026, on 0.66.1, Claude asked Align over MCP before it tried an edit, so the hook never fired. It cited #7089 and #601 (2018: "do not allow set status code to lower than 400"), changed nothing, and asked what to do. Models are not deterministic, so your run may word it differently.

On 6 Nov 2026 we ran the same prompt in Align's own agent, once on Claude Code and once on an OpenAI key. Both times the agent tried the edit, Align found #7089 from git blame and asked first, and after "stop" the agent cited #7089 and changed nothing.

Install

• npm: npm install -g @aligndottech/cli (Node 22.19+).
• macOS / Linux, no Node: curl -fsSL https://align.tech/install.sh | sh installs a standalone binary and checks it against the release checksums. Read install.sh first if you like.
• Windows: npm in PowerShell. The curl line needs a POSIX shell (Git Bash or WSL). Without Node, download align-windows-x64.exe (or -arm64) from the releases page, rename it to align.exe and put it on your PATH.

More in docs/installation.md.

How it works

1. Import. Reads decisions from Git (commits that state a reason), the repo's ADRs, CLAUDE.md and AGENTS.md, GitHub, GitLab, Jira, Confluence, Linear, Notion, Slack, Teams and Zoom. Read-only. In a repo, GitHub and GitLab (gitlab.com) read that repo, as far as your token can see. For Jira, Linear, Confluence and Notion you pick what belongs to it (a Jira project, board or filter, Linear projects, Confluence page trees, Notion pages) or skip the source there. Each repo keeps its own choice (Importing).
2. Link. Records what was decided, why and by whom. Related decisions surface as related. Telling replaced from conflicting needs an AI key locally, or a team graph.
3. Check. Your agent queries the graph over MCP, an edit hook, CI or align ask.

align wires it in four ways, so the check runs whether or not the model thinks to ask:

Before writing anything, setup lists every file it will create or change, with files outside your project (an agent's own config, user-level hooks) under their own heading, and asks. With no terminal to ask in (an agent's shell, CI) it writes nothing unless you pass --approve.

To undo everything align wrote, run align use --undo.

The hook never blocks on a model's judgement unless you turn blocking on, and that needs an AI key. One thing can deny without it, on a team graph: a rule your team ratified (secrets, card numbers, emails), when the edit contains one. If Align is slow, errors or times out, the edit goes ahead. If you uninstall align, rerun align mcp --setup: an older Copilot CLI hook file can deny edits until it is rewritten.

Hook limits worth knowing:

• Cursor, Copilot CLI and Gemini CLI only hand the result to the model after the edit lands. That's a limit of their hook APIs.
• Only Claude Code's hook has been run in a live session. pi, Gemini CLI and OpenCode are written from the vendors' docs or source, and Codex, Cursor and Copilot CLI have not been checked against a real payload. The last three read hooks from a user-level file (~/.codex/hooks.json, ~/.cursor/hooks.json, ~/.copilot/hooks/align.json).
• pi reads MCP servers itself from 0.99 and later, and an older pi needs the third-party pi-mcp-adapter package installed in it. pi also blocks a repo's MCP servers until you trust the project, and Align's entry counts as one, so accept pi's trust prompt or Align's tools won't load. pi -p skips the prompt and runs without them.
• Claude Code asks you to approve a committed hook the first time. Accept, or it won't run.
• Codex skips a hook in ~/.codex/hooks.json until you approve it in Codex's one-time hook trust review, and codex exec never asks, so open Codex once interactively after align setup.
• In a headless run (claude -p) Claude Code can't ask you to approve tools, so it denies Align's MCP tools unless you allow them, for example "permissions": {"allow": ["mcp__align"]} in .claude/settings.json. align setup deliberately doesn't add that for you. The edit hook needs no permission and runs either way.

Per-host details.

Your first five minutes

Setup ends with three prompts to type into your agent, built from your own repo:

1. why did we switch to postgres?                     learn why the code is the way it is

1. what was decided about src/db/pool.ts? before you touch a file
2. Plan a change that reverses "switch to postgres". watch the agent stop and cite the decision Check it with Align before writing anything.

After that the check runs on its own on every edit, and the agent tells you in one line when it found a related decision. Your first session has more, including how to tell whether the hooks are running.

Everyday commands

align                                # set up, or see your graph and what to do next

align ask "how does our auth work" # an answer, with sources align ask src/auth/session.ts # decisions about a file align connect # pick a source to import: git, docs, jira, github, ... align connect jira --token ... # import one source directly align check # check your staged diff against the graph align mcp --setup # wire your agent to the graph

To make tickets from a decision, ask your agent: "make tickets for that decision". It shows you the plan first (tracker, team, the task titles) and creates nothing until you say yes. align backlog does the same from a terminal.

Local mode keeps the read-only tokens you paste in your OS credential store, and reads ALIGN_ _TOKEN first if you use a password manager. See Importing.

align --help lists ask, connect, check, backlog, share (alias push), mcp and agents. The rest (search, decisions, stale, export, ratify, context, ...) still work and are in docs/commands.md.

Something not working? align doctor checks Node, that align is on your PATH, that the gateway answers, that your token is accepted, and that one real question comes back through align mcp. It names the next step for each failure and exits non-zero if any check fails. It sends no telemetry.

Inside your agent, the agent writes the answers, so you don't need an AI key. Only align ask in a terminal writes its own. Give it a key (Anthropic, OpenAI, OpenRouter, Gemini, Groq, Mistral or xAI), a local Ollama, or any OpenAI-compatible endpoint. W