Align Cli MCP Server

Align CLI

AI agents are shipping code from decisions they can't see.

Align captures the reasoning behind every engineering choice - across Git, GitHub, GitLab, Jira, Confluence, Linear, Slack, Microsoft Teams, Zoom, and Notion - links them into a cross-tool decision graph, and surfaces that context to every agent and engineer on your team.

The CLI lets you import your decision history, query it in plain English, and run Align as a local MCP server so your AI assistants have authoritative context inline - and check their changes against it automatically.

npm install -g @aligndottech/cli

Node 20+ required. MIT licensed.

Install notes. Cloud mode needs no native build. --local mode additionally uses an on-device embedding model (@huggingface/transformers, an optional dependency) that ships native binaries for macOS, glibc Linux, and Windows (x64/arm64) - on those platforms npm i -g just works. On Alpine/musl, uncommon architectures, or behind a strict proxy the optional model may not install; the global install still succeeds and cloud mode works, and --local will tell you the model is unavailable rather than failing silently. The first --local import downloads the model (~90MB) once.

Quick start

align setup

One guided command: login (or local-only mode), connect your tools via read-only OAuth, seed the graph from your git history, configure your editors' MCP, and wire up automatic alignment checks for AI agents.

Or step by step:

align login                              # authenticate
align setup                              # connect tools (read-only OAuth) + configure MCP
align import git                         # pull commit history - no token needed
align ask "how does our auth work"       # natural language answer from your graph

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

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 the decisions out of the tools you already use - read-only, nothing is modified.
2. Align links them into a cross-tool decision graph: what was decided, why, who decided it, and how decisions relate (supersedes, conflicts with, depends on).
3. Your agents and you query and check against that graph - over MCP, a deterministic edit hook in your agent, CI, or plain align ask.

The CLI and MCP server are open source (this repo). The hosted graph + relationship detection is a separate commercial gateway; you can also run fully local with --local.

Auto-alignment for AI agents

When you run align setup, Align makes itself available to your AI agents four ways, so the context fires whether or not the model thinks to ask for it:

1. MCP server - your assistant (Claude Code, Cursor, Claude Desktop, Windsurf) can query the decision graph inline. The server ships with instructions telling the agent to check alignment before making non-trivial changes.

2. Deterministic edit hooks - setup registers align check --advisory with every host that exposes a hook API, so prior decisions related to the change reach the model whether or not it thought to ask. Claude Code (.claude/settings.json), pi (.pi/extensions/align.ts), Gemini CLI (.gemini/settings.json) and OpenCode (.opencode/plugins/align.js) all check the proposed change before it is written. It 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.

   Cursor and Codex CLI cannot do this, and that is a limit of those hosts, not a gap in setup: Cursor has no beforeFileEdit and its afterFileEdit hook has no output fields, and Codex's PreToolUse intercepts Bash only. They get layers 1, 3 and 4. The full per-host matrix, and why, is in docs/agent-hooks.md.

3. Editor rules - a managed, marker-delimited block in your CLAUDE.md and AGENTS.md, plus a .cursor/rules/align.md file (Cursor doesn't honor Claude Code hooks), nudge agents to consult the graph.

4. A shared .mcp.json at the repo root - the tool-agnostic MCP config that pi, Claude Code and others read, so one committed file wires up the whole team rather than each person's per-host config.

The hook, rule and .mcp.json files are committed to the repo, so the whole team's agents get the same guardrail. Re-running align setup updates them in place (idempotent - no duplicate hooks or blocks).

Heads up: 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.

You can also run the advisory check yourself. It always exits 0, and when it finds related prior decisions (or could not check at all) prints the hook output in whichever host's shape you ask for - --format text is plain prose for a host with no JSON contract. It reports the decisions as related, not as conflicts: retrieval finds decisions on the same subject and does not adjudicate opposition.

align check --advisory                  # Claude Code shape (default)
align check --advisory --format text    # plain text, for any other agent

Asking questions

align ask retrieves the most relevant decisions from your graph and synthesises a concise natural language answer:

align ask "why do we use postgres"
align ask "how does the auth module work"
align ask "what was decided about caching"
align ask "do we use redis"

Ask in plain English - the graph picks keyword or semantic search automatically based on your phrasing, so full questions ("why do we use postgres") work as well as short terms ("postgres"). Pass a file path instead of a question to find decisions related to that file:

align ask src/auth/session.ts

AI provider for conversational answers

Align is provider-agnostic - align ask (and local relationship typing) uses your own AI provider. It resolves one, in order:

1. A named provider via env key: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY (or GOOGLE_API_KEY), GROQ_API_KEY, MISTRAL_API_KEY, or GROK_API_KEY (or XAI_API_KEY). Each has an optional model override (ALIGN_ANTHROPIC_MODEL, ALIGN_OPENAI_MODEL, ALIGN_GEMINI_MODEL, ALIGN_GROQ_MODEL, ALIGN_MISTRAL_MODEL, ALIGN_GROK_MODEL).

2. Any OpenAI-compatible endpoint via ALIGN_LLM_BASE_URL (+ ALIGN_LLM_API_KEY, ALIGN_LLM_MODEL) - covers OpenRouter, Together, DeepSeek, LM Studio, vLLM, or any self-hosted OpenAI-compatible server. Example:

   export ALIGN_LLM_BASE_URL=https://openrouter.ai/api/v1
   export ALIGN_LLM_API_KEY=sk-or-...
   export ALIGN_LLM_MODEL=anthropic/claude-3.5-sonnet
   

3. Ollama running locally (auto-detected on localhost:11434, override OLLAMA_HOST), with one of llama3.2, llama3.1, llama3, mistral, gemma2 or phi3 installed.

   Ollama will not answer from a model outside that list. A model tuned for something else entirely will still write fluent prose about your decisions, including relationships between them that do not exist, and it is not obvious from the output that anything went wrong. To use a model that is not listed, name it and it is used as-is:

   export ALIGN_OLLAMA_MODEL=qwen2.5:14b
   

If none is available, align ask still works - it prints a ranked list of the matching decisions instead of a synthesised paragraph. No key is ever required.

Note: A Claude.ai or ChatGPT subscription is not the same as an API key - you need a separate API account. Groq offers a free tier with no credit card and is the fastest option.

The retrieval itself (search over your graph) always runs against Align - the API key is only used locally to phrase the answer.

Authentication

align login                  # opens browser, paste token when prompted
align login --token algt_...  # non-interactive, good for CI / self-hosted
align whoami                 # verify current session
align logout                 # clear stored credentials

Tokens are stored locally in your OS config directory. To create one manually, go to Settings > API Tokens in the Align web app.

Cloud vs local mode

align setup offers two modes:

• Personal cloud (default) - your decision graph is hosted at Align: synced across machines, backed up, and upgradeable to a shared team workspace. Connectors connect via read-only browser OAuth (no tokens to paste), and align ask retrieval runs server-side. Nothing you connect can be modified by the CLI - it only reads.
• Local-only (align setup --local) - fully private and offline: no account, no cloud, nothing leaves your machine. The graph, embeddings, and search all live in a local database. Seeds from your git history out of the box; other sources connect by pasting a read-only personal token (OAuth needs the hosted callback, so it isn't available offline). Related decisions are surfaced on-device by semantic similarity; typed relationships (supersedes / conflicts with / depends on) and conflict detection on a change are typed at query time using your own AI provider key (Anthropic, OpenAI, or a local Ollama) - without one, related decisions still surface, just not typed. The heavier cross-tool relationship detection runs in the hosted gateway. Run align local status to inspect it, align local reset to wipe it.

Pick cloud for sync + team upgrade, local for maximum privacy. You can always start local and move to cloud later.

Importing decisions

Pull your existing work into the decision graph. The more sources you add, the richer the cross-tool relationship detection.

Easiest way: align setup. It connects each source via a read-only browser OAuth consent - no tokens to create or paste. The CLI only ever reads; it can't modify your tools (write access lives only in the team/org bot apps). GitHub, Jira, Confluence, Slack, Microsoft Teams, Zoom, Linear, GitLab (gitlab.com), and Notion all use OAuth. Self-managed GitLab (a custom domain) uses a read-only token you paste.

The same OAuth flow also works per source: align import <source> --personal opens the browser consent (or reuses the token a previous align setup cached) - no PAT to create. The align import <source> --token ... forms below are the manual / CI alternative (and how to connect self-managed hosts). Every import previews what will be imported and asks for confirmation before sending anything (use --approve to skip the prompt).

Git

align import git

GitHub / GitLab

Prefer align setup - GitHub and gitlab.com connect via read-only OAuth (no token to create). Manual / self-managed alternative:

align import github --token ghp_...      # or connect via `align setup` (read-only OAuth)
align import gitlab --token glpat-...     # self-managed GitLab: create a read_api (read-only) token

Jira

align import jira \
  --token <your-jira-api-token> \
  --email your@email.com \
  --domain yourorg.atlassian.net

Linear

Prefer align setup - Linear connects via read-only OAuth (scope read). Manual alternative:

align import linear --token lin_api_...

Confluence

align import confluence \
  --token <your-confluence-api-token> \
  --email your@email.com \
  --domain yourorg.atlassian.net

Slack (experimental)

Prefer align setup - Slack connects via read-only OAuth (read scopes only, no chat:write). Note: the Slack app must have public distribution enabled, or you authorize from its home workspace.

Manual alternative: align import slack requires a Slack user token (xoxp-...), not a bot token.

To get one: go to api.slack.com/apps, create an app, add these User Token Scopes under OAuth & Permissions: channels:read, channels:history, groups:read, groups:history. Install to your workspace and copy the OAuth User Token.

align import slack --token xoxp-<your-slack-user-token>

Notion

Create an internal integration with only "Read content" capability (no insert/update), then paste its secret:

align import notion --token <your-notion-integration-token>

Microsoft Teams / Zoom

Connect these through align setup (OAuth) - they have no read-only personal token to paste, so they are cloud-only.

Capturing decisions

# Capture a decision from a URL - the platform is detected automatically
align capture https://github.com/org/repo/pull/42
align capture https://yourco.atlassian.net/browse/ENG-123
align capture https://yourco.slack.com/archives/C123/p1700000000000000

Searching and browsing

align ask "any question in plain English"  # natural language answer
align search "authentication strategy"      # keyword/semantic search - returns a list
align decisions list                        # browse the graph
align decisions list --space backend        # filter by space
align decisions list --platform jira        # filter by source platform
align decisions show <id>                   # full detail for one decision
align links list                            # cross-tool decision relationships
align drift                                 # decisions that may be out of date
align export                                # export decisions as a structured brief

align ask synthesises an answer. align search returns a ranked list - useful when you want to browse.

Alignment check

Check your current changes against the decision graph. Exit code 1 means a conflict was found; 2 means the check could not run and nothing was verified, which is not a pass.

align check          # check the staged diff
align check --all    # check the full working-tree diff vs HEAD

Modes:

In CI:

- name: Check alignment
  run: align check --all --ci
  env:
    ALIGN_TOKEN: ${{ secrets.ALIGN_TOKEN }}

Resolve a flagged conflict (records the resolution so it stops surfacing):

align check --resolve <decision_id>:honored      # or overridden | context_changed

Write decisions into your agent's context files

Agents read local files before they reach for any tool. align context sync writes your current decisions to .align/decisions.md and adds one import line to CLAUDE.md, so an agent knows what your team decided without a single tool call.

align context sync           # write .align/decisions.md, import it from CLAUDE.md

Align owns .align/decisions.md outright and regenerates it on each sync - your CLAUDE.md is never rewritten, only ever appended with the single @.align/decisions.md line, once. If the repo has no CLAUDE.md, the command prints the line to add instead of inventing a file. Re-run after new decisions land; unchanged decisions produce a byte-identical file, so syncing never dirties a clean tree.

MCP server

Run Align as a local Model Context Protocol server so AI assistants (Claude Code, Claude Desktop, Cursor, Windsurf) can query your decision graph inline.

align mcp --setup   # auto-configure detected editors
align mcp           # start the server directly

Manual configuration

Claude Desktop - ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "align": {
      "command": "align",
      "args": ["mcp"],
      "env": { "ALIGN_TOKEN": "algt_..." }
    }
  }
}

Claude Code - ~/.claude.json or your workspace .mcp.json:

{
  "mcpServers": {
    "align": { "command": "align", "args": ["mcp"] }
  }
}

Cursor - ~/.cursor/mcp.json (same format as Claude Code above).

pi - MCP is not built in; install the adapter first with pi install npm:pi-mcp-adapter, then restart pi. align setup writes ~/.pi/agent/mcp.json (or $PI_CODING_AGENT_DIR/mcp.json):

{
  "mcpServers": {
    "align": { "command": "align", "args": ["mcp"], "directTools": true }
  }
}

directTools matters: the adapter is lazy by default and hides every server behind a single proxy tool the agent has to search first, which defeats the "check alignment before the edit" instruction.

Once configured, your assistant can call these tools to query and update your decision graph in context:

Environments

By default the CLI targets prod (api.align.tech). Use --env or set a sticky default:

align env set preview          # stick to preview for this machine
align env get                  # show current default
align --env local <command>    # one-off override

Environment variables

Advanced: override the model per provider with ALIGN_ANTHROPIC_MODEL, ALIGN_OPENAI_MODEL, ALIGN_GEMINI_MODEL, ALIGN_GROQ_MODEL, ALIGN_MISTRAL_MODEL, ALIGN_GROK_MODEL, or ALIGN_OLLAMA_MODEL.

Self-hosted

align login --env local --token algt_...
# or
ALIGN_GATEWAY_URL=https://api.yourco.com align decisions list

ALIGN_GATEWAY_URL changes where the CLI talks to; --env changes how it authenticates, and the two are independent. That matters if you also set ALIGN_TENANT_ID, because a tenant with nothing authenticating it is refused in prod/preview (auth mode):

With no --env the CLI defaults to prod, which authenticates. So ALIGN_TENANT_ID set on its own, with no token, is refused rather than sent: it cannot succeed against a gated route, and against an ungated one it would read a tenant you were never authorised for.

Command reference

align setup                  Guided onboarding: connect tools, configure MCP + auto-alignment
align login                  Authenticate with Align
align logout                 Remove stored credentials
align whoami                 Show current authenticated user and tenant
align ask <query>            Ask a natural language question (or pass a file path)
align search <query>         Keyword/semantic search - returns a ranked list
align capture <url>          Capture a decision from a URL (platform auto-detected)
align check                  Check current changes against the decision graph
align import git             Import from Git commit history (no auth)
align import github          Import from GitHub
align import gitlab          Import from GitLab
align import jira            Import from Jira
align import linear          Import from Linear
align import confluence      Import from Confluence
align import slack           Import from Slack (experimental)
align import teams           Import from Microsoft Teams
align import zoom            Import from Zoom recording transcripts
align import notion          Import from Notion
align decisions list         List decisions in your graph
align decisions show <id>    Show full detail for a decision
align status                 Value readout: what your graph has done for you
align context sync           Write decisions to .align/decisions.md + CLAUDE.md import
align export                 Export decisions as a structured brief
align drift                  Show decisions that may be out of date
align links list             Show cross-tool decision relationships
align spaces list            List spaces (project scopes)
align env set <name>         Set default environment
align env get                Show current environment
align mcp                    Start local MCP server
align mcp --setup            Auto-configure editors to use Align as MCP server
align local start            Initialize a local decision graph
align local status           Show local graph statistics
align local reset            Wipe the local graph

License

MIT - see LICENSE. The CLI and MCP server are open source; the hosted gateway is a separate commercial service.