cli

Align CLI

你的 AI Agent 了解代码，却不了解公司。

Align 会从提交记录、工单、聊天和会议中收集团队的决策，并汇总到一张图谱中。 你的编码 Agent 可以查询代码背后的决策及其来源， 然后再修改代码。

npm install -g @aligndottech/cli
align

没有 Node？运行 curl -fsSL https://align.tech/install.sh | sh 即可安装独立二进制文件。

同一条提示词，在 Align 自身的代码库上实际运行两次（2026 年 10 月 14 日）。文本 摘自这两次运行并经过缩短。GIF 会重放运行过程，并非实时会话（原理）。 未使用 Align 时，Agent 计划跳过签名检查；使用 Align 后，Agent 停下来，并引用了排除该做法的 决策。

在 git 仓库中运行。首次运行时，程序会询问你使用哪种 Agent，根据提交 历史构建图谱，并完成 Agent 的接入。之后，运行 align 会打开已连接图谱的 Agent， 并在后台刷新已连接的数据源，每个数据源最多每 15 分钟刷新一次 （运行 align sync --off 可关闭此功能）。

MIT 许可，无需账户。Beta 阶段，尚未达到 1.0 版本。

安装

• npm：npm install -g @aligndottech/cli（Node 22.16+）。
• **macOS / Linux，无需 Node：**运行 curl -fsSL https://align.tech/install.sh | sh，即可安装 独立二进制文件，并通过发布校验和验证文件。你也可以先阅读 install.sh。
• **Windows：**在 PowerShell 中使用 npm。curl 命令需要 POSIX shell（Git Bash 或 WSL）。如果没有 Node，请从发布页面 下载 align-windows-x64.exe（或 -arm64），将其重命名为 align.exe 并放到 PATH 中。

更多信息请参阅 docs/installation.md。

工作原理

1. 导入。 从 Git（说明原因的提交）、GitHub、GitLab、Jira、Confluence、Linear、Notion、Slack、 Teams 和 Zoom 读取决策。只读。
2. 关联。 记录决策内容、原因和决策者。相关决策会显示为相关项。要区分被取代的决策与相互冲突的需求，需要在本地配置 AI 密钥，或使用团队图谱。
3. 检查。 你的 Agent 通过 MCP、编辑钩子、CI 或 align ask 查询图谱。

align 通过四种方式接入，确保无论模型是否想到要查询，都会执行检查：

MCP 服务	Claude Code、Cursor、Claude Desktop、VS Code、Windsurf、Zed、Codex、Copilot CLI、Gemini CLI、pi、OpenCode
编辑钩子	每次编辑都会根据图谱进行检查。默认仅提供建议。支持 Claude Code、pi、Gemini CLI、OpenCode、Codex、Cursor、Copilot CLI
编辑器规则	在 CLAUDE.md、AGENTS.md 和 .cursor/rules/align.md 中写入受管理的代码块
共享 .mcp.json	提交一个文件即可为整个团队完成设置

要撤销 align 写入的所有内容，请运行 align use --undo。

除非你启用阻止功能，否则钩子绝不会根据模型的判断进行阻止；启用阻止功能需要 AI 密钥。无需密钥也能阻止一种情况：在团队图谱中，团队批准了一条规则（涉及机密、卡号、 电子邮件），且编辑内容包含相关内容时。如果 Align 运行缓慢、出错或超时，编辑仍会继续。如果你卸载了 align，请重新运行 align mcp --setup：较旧的 Copilot CLI 钩子文件可能会阻止编辑，直到文件被重写。

钩子的一些限制值得了解：

• Cursor、Copilot CLI 和 Gemini CLI 只会在编辑完成后将结果交给模型。 这是它们的钩子 API 所限。
• 只有 Claude Code 的钩子经过实时会话测试。pi、Gemini CLI 和 OpenCode 的钩子是根据 厂商文档或源代码编写的；Codex、Cursor 和 Copilot CLI 的钩子尚未通过真实负载验证。 后三者从用户级文件读取钩子（~/.codex/hooks.json、 ~/.cursor/hooks.json、~/.copilot/hooks/align.json）。
• pi 的 MCP 配置需要先在 pi 中安装第三方软件包 pi-mcp-adapter。
• Claude Code 首次运行时会要求你批准已提交的钩子。请接受，否则钩子不会运行。

各宿主的详细信息。

前五分钟

设置流程最后会根据你自己的代码仓库生成三个提示词，供你输入 Agent：

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

之后，每次编辑都会自动运行检查；发现相关决策时，Agent 会用一行话告诉你。首次会话 提供了更多信息，包括如何 确认钩子是否正在运行。

日常命令

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

align --help 会列出 ask、connect、check、share（别名为 push）、mcp 和 agents。其余命令（search、decisions、export、ratify、context，等等）仍可使用，详见 docs/commands.md。

遇到问题？align doctor 会检查 Node、align 是否位于 PATH 中、网关是否响应、令牌是否通过验证，以及是否能通过 align mcp 成功返回一个真实问题的答案。它会针对每项失败指出下一步操作；如果任何检查失败，退出状态将为非零。不会发送任何 遥测数据。

在 Agent 中，由 Agent 编写答案，因此你不需要 AI 密钥。只有在终端中运行 align ask 时，才会由它自行编写答案。你可以为它提供密钥（Anthropic、OpenAI、OpenRouter、Gemini、Groq、 Mistral 或 xAI）、本地 Ollama，或任何兼容 OpenAI 的端点。如果没有配置，它会列出 匹配的决策，并提供设置免费 Groq 密钥的选项（无需银行卡）。如果配置了多个密钥，align ai 会选用其中一个。设置方式。

隐私与遥测

本地图谱是你设备上的 SQLite 文件，嵌入在设备上运行，只需从 huggingface.co 下载一次约 23MB 的模型。在纯本地模式下，你的决策和代码绝不会发送给 Align。如果你设置了 AI 密钥或运行 Ollama，align ask 会将你的问题以及它找到的决策标题和摘要发送给你的服务提供商，而不是 Align；align check 会将最多 2,000 个字符的拟议更改发送给你的服务提供商，而不是 Align（MCP 检查也会如此）。无论 OLLAMA_HOST 指向哪里，Ollama 都由你掌控。团队图谱由 Align 托管，或可自托管，供团队共享。

纯本地模式会发送匿名使用次数。首次发送前会告知你一次，且不会从 CI 发送任何数据。登录团队图谱后，使用事件会通过你已在使用的连接发送，且默认开启。无论哪种情况，align telemetry off 都会停止发送。 网络访问情况和我们发送的每个字段。

团队

团队图谱需要通过邀请加入：管理员会向你发送链接，然后你运行 align join（文档）。已经有团队图谱？运行 align login，然后运行 align。设置过程会通过只读 OAuth 连接你的工具，并配置好编辑器。目前，创建新的团队图谱需要预约通话：未登录团队时运行 align share，即可跳转到 30 分钟预约页面。

个人邮箱无法创建云端图谱，因此个人使用时会采用本地图谱。登录绝不会在你不知情的情况下切换到本地模式，而 align --env local 会在不触碰登录状态的情况下构建本地图谱。加入团队。

文档

安装	npm、二进制文件、Windows
首次会话	三个提示词，以及如何判断检查正在运行
加入团队图谱	align join、托管和自托管
导入	所有来源、令牌、标志
一致性检查	模式、退出代码、CI、GitHub Action
云端或纯本地	各项功能的运行位置、网络访问情况
遥测	每个事件和字段，以及如何关闭遥测
MCP 服务	编辑器配置、Agent 可用的工具
配置	AI 服务提供商、环境变量、身份验证、自托管
Agent 钩子	各主机的功能与限制
选择访问方式	API、CLI JSON 或 MCP，以及原因
所有命令	完整参考

为什么要用

一项已发表的研究为编码 Agent 提供了有据可查的产品决策，发现其遵循决策的比例从 46% 提升到 95% （Dillon & Varanasi，arXiv:2605.08112）。这是一项小型供应商研究，包含 8 项任务和 41 个决策点，而且数据并非来自我们。

将上下文接入 Agent 很容易，这也是本仓库的用途。难点在于跨所有工具，持续准确记录团队实际做出的决策。

需要帮助设置吗？我提供免费的 30 分钟通话：https://calendly.com/tom-align/setup

许可证

MIT，详见 LICENSE。CLI、MCP 服务和连接器 SDK均为开源。托管团队产品是独立的商业服务。