align-cli

# Align CLI

[![npm version](https://img.shields.io/npm/v/@aligndottech/cli.svg)](https://www.npmjs.com/package/@aligndottech/cli)
[![CI](https://github.com/aligndottech/align-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/aligndottech/align-cli/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Node](https://img.shields.io/node/v/@aligndottech/cli.svg)](https://nodejs.org)

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

The decisions behind the code live in commits, tickets, chat and meetings. Months later nobody
can tell what still stands, what conflicts, or why. Align pulls them into one graph your agents
check before they build.

```bash
curl -fsSL https://align.tech/install.sh | sh
align
```

That is the whole thing. The first time you run it, `align` asks which coding agent you use,
connects your tools and builds a local graph on your machine. After that, `align` opens your
agent with the graph already wired in.

A standalone binary. No Node, no npm, nothing else to install, and local-only mode works
fully - on-device embeddings included, running on a WASM backend bundled inside the binary.
Linux, macOS and Windows, x64 and arm64, glibc and musl. It checks the download against the
release's own checksums and says so out loud when it cannot, and you can read
[install.sh](install.sh) before you pipe it anywhere.

Prefer npm, or already have Node? `npm install -g @aligndottech/cli` (Node 22.16+).
Binaries for every platform are on the [releases page](https://github.com/aligndottech/align-cli/releases/latest).

**On Windows, start with npm.** In PowerShell:

```powershell
npm install -g @aligndottech/cli
align
```

The `curl ... | sh` line above needs a POSIX shell, so it runs under Git Bash or WSL and not in
PowerShell itself. [Installing](docs/installation.md) covers the rest, including the manual
binary download for a Windows machine with no Node on it.

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

Run it inside a git repository. `--local` seeds the graph from your commit history, so you have
something to ask about straight away, and your decisions stay in a SQLite file on your machine.
Your decisions and code never go to Align. It sends anonymous usage counts, and tells you so
once, before the first one. `align telemetry off` or `DO_NOT_TRACK=1` stops all of it, and
nothing is sent from CI. [What touches the network](docs/local-mode.md), and
[every field](docs/telemetry.md).

Working with a team? Team graphs are separate from the local one. Run `align login`, then
`align setup`: a work email lands you in your company's graph (first person in is the admin, the
next colleague on that domain joins it automatically), and setup connects your tools through
read-only OAuth and wires up your editors. A personal email does not get a cloud graph; solo use
is the local graph that `align` builds. A team login is never switched to local behind your
back: `align setup --env local` builds the local graph on purpose and leaves the login alone.

## How it works

```
  Your tools                      Align                       Your agents & you
  ──────────                   ───────────                  ───────────────────
  Git, GitHub, GitLab  ─┐                                  ┌─ align ask "why…"
  Jira, Confluence      ├─▶  import  ─▶  decision graph ─┐ ├─ MCP server (inline)
  Linear, Notion        │    (read-only) (what/why/who)  ├─┤  edit hooks (any agent)
  Slack, Teams, Zoom   ─┘                  + relationships┘ └─ align check (CI)
```

1. **Import** pulls decisions out of the tools you already use. Read-only, nothing is modified.
2. Align links them into a **decision graph**: what was decided, why, who decided it, and how
   decisions relate (supersedes, conflicts with, depends on).
3. Your agents **query and check against** it, over MCP, an edit hook, CI, or `align ask`.

## Your agent checks before it writes

`align setup` wires Align in four ways, so context fires whether or not the model thinks to ask.

| | What you get |
|---|---|
| **MCP server** | Claude Code, Cursor, Claude Desktop, VS Code, Windsurf, Zed, Codex, Copilot CLI, Gemini CLI, pi and OpenCode query the graph inline |
| **Edit hooks** | Prior decisions reach the model before it writes. Claude Code, pi, Gemini CLI, OpenCode |
| **Editor rules** | A managed block in `CLAUDE.md`, `AGENTS.md` and `.cursor/rules/align.md` |
| **Shared `.mcp.json`** | One committed file wires up the whole team |

The hook is **non-blocking and fail-open**. It never denies an edit by default, and if Align is
missing, slow or unreachable the edit proceeds untouched. It needs no AI provider key.

Cursor and Codex CLI can't do the pre-edit hook, and that's a limit of those hosts. They get the
other three. Full per-host matrix: [docs/agent-hooks.md](docs/agent-hooks.md).

> The first time Claude Code loads a project with a committed hook, it shows a one-time "approve
> hooks" prompt. Accept it to enable automatic alignment.

## Everyday commands

```bash
align                                # set up, or see your graph and what to do next
align ask "how does our auth work"   # natural language answer with sources
align ask src/auth/session.ts        # a file path finds decisions about that file
align connect                        # pick a source to import: git, docs, jira, github, ...
align connect jira --token ...       # one source, straight in
align check                          # check your staged diff against the graph
align mcp --setup                    # wire your agent to the graph
```

That is the whole of `align --help`. Every other command (`search`, `decisions`, `export`,
`ratify`, `push`, `context`, `local`, ...) still works and is listed in
[docs/commands.md](docs/commands.md).

Inside your coding agent, the agent writes the answers - align needs no AI key for that. Only
`align ask` in the terminal writes prose itself, and without a provider it returns the matching
decisions as a ranked list. The first time that happens on a terminal, `align ask` offers to add
a key you already have (Anthropic, OpenAI, OpenRouter, Gemini, Groq, Mistral, xAI) or a free Groq
key (no card, ever). A local Ollama or any OpenAI-compatible endpoint works too, and `align ai`
picks which one is used when you have several. [Setting one up](docs/configuration.md#ai-provider).

## Docs

| | |
|---|---|
| [Installing](docs/installation.md) | npm, the binary, Windows and PowerShell |
| [Importing](docs/importing.md) | Every source, tokens, flags |
| [Alignment check](docs/check.md) | Modes, exit codes, CI, the GitHub Action |
| [Cloud or local-only](docs/local-mode.md) | What runs where, what touches the network |
| [Telemetry](docs/telemetry.md) | Every event and field, and how to stop it |
| [MCP server](docs/mcp.md) | Editor config, the tools your assistant gets |
| [Configuration](docs/configuration.md) | AI providers, env vars, auth, self-hosting |
| [Agent hooks](docs/agent-hooks.md) | Per-host capability matrix |
| [Choosing an access path](docs/access-capability.md) | API vs CLI JSON vs MCP, and why |
| [All commands](docs/commands.md) | Full reference |

## Why bother

In a published benchmark, giving a coding agent recorded product decisions took decision
compliance from 46% to 95%
([Dillon & Varanasi, arXiv:2605.08112](https://arxiv.org/abs/2605.08112) - a small vendor study,
8 tasks and 41 decision points, and it isn't our data).

Wiring context into an agent is the easy part, and this repo is the open-source version of it.
The hard part is the record underneath: what your team actually decided, across every tool, kept
current.

Want a hand setting it up? I do free 30 minute setup calls:
https://calendly.com/tom-align/setup

## License

MIT, see [LICENSE](./LICENSE). The CLI and MCP server are open source, along with the
[connector SDK](https://github.com/aligndottech/align-connector-sdk). The hosted gateway is a
separate commercial service.