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)

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

[Align](https://align.tech) 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](https://modelcontextprotocol.io) 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

```bash
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:

```bash
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](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.

```bash
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:

```bash
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:

```bash
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:
   ```bash
   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](https://ollama.com) 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:

   ```bash
   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](https://console.groq.com/keys) 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

```bash
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 i