Mach 完全指南：为 AI Agent 打造 Git 版本控制
AI 编码工具已经成为开发者的日常伙伴——Claude Code、Codex、OpenCode、Gemini CLI……但有一个问题始终困扰着每个重度用户：Agent 的工作过程是个黑盒。
Agent 做了什么？为什么改了那行代码？之前那个状态能不能回溯？当 Agent 犯错时，你怎么证明它做错了？如果团队多人协作，如何交接 Agent 会话？
Mach 给出了一个新答案：把 AI Agent 的执行过程像 Git 一样管理起来。
什么是 Mach？
Mach 是一个本地优先的 AI Agent 执行记录系统（Execution Ledger），由 Cognato AI 团队开发。它运行在你的 Git 仓库旁边，自动拦截和记录 Agent 的每一步操作——推理过程、输入输出、工具调用、文件变更——形成一份可加密验证、可搜索、结构化的完整执行历史。
简单说：Git 管理的是代码版本，Mach 管理的是 Agent 的决策版本。
核心能力
- 自动拦截：自动 HOOK Claude Code、Codex、Gemini CLI、Copilot CLI 等终端型 Agent
- Git 式 Blob 存储：大型 Agent 输出进行哈希去重，存储在
.mach/blobs/中，核心 JSONL 日志轻量可解析 - 加密验证：每次 Agent 操作都经过哈希链式验证，不可篡改
- TUI 仪表盘：
mach log命令打开交互式终端界面，按/实时全文搜索 - 远程协作：支持
mach push/mach clone在团队间共享 Agent 会话
安装
Mach 要求 Python 3.9+。
推荐方式——独立安装脚本：
curl -fsSL https://raw.githubusercontent.com/cognato-ai/mach/master/install.sh | bash
或者用 pipx：
pipx install git+https://github.com/cognato-ai/mach.git
安装后可以用 mach update 更新，mach --help 查看所有命令。
快速上手
进入你的项目目录，初始化 Mach：
mach login --token <你的 PAT Token> mach init mach init --hook-agents claude,codex,gemini --store-content input,output,reasoning,tool
初始化完成后，Mach 的后台守护进程会自动启动。你正常使用 Agent 即可——Mach 会在后台悄无声息地记录每一步。
查看执行记录
mach log
在 TUI 中：
- 方向键 / Tab 切换会话和事件时间线
- Enter 查看详情的文件差异和原始内容
/按工具名、AI 推理内容或文件名搜索
保存和共享会话
mach pushmach clone my-repo ses_123
克隆后的会话会创建一个本地分叉，新的本地步骤不会覆盖远程原始记录——类似 Git 的分支机制。
核心架构解析
Mach 的架构有几个值得关注的设计：
Git 式 Blob 存储： Agent 每一步的输入、输出、推理、工具调用都被哈希后去重存储。大型内容（如完整代码文件）只存一次哈希，后续引用同一内容不会重复占用空间。
混合索引： Mach 默认使用 SQLite FTS5 全文索引实现毫秒级搜索。在资源受限的环境中，可以通过 mach config set --db-enabled false 关闭索引，降级为纯文件系统遍历——就像 Git 一样。
零延迟采集： Agent 事件通过异步收件箱（Async Inbox）处理，后台守护进程批量写入，保证不会对你的实际 Agent 工作流造成任何延迟。
Workspace Observer： 如果 Agent 修改了文件但未能正确报告（或者你在 Agent 执行期间手动编辑了文件），守护进程会检测这些”孤儿”文件变更并记录为 workspace_observer，确保执行记录的完整性。
关键命令速查
| 命令 | 功能 | |
|---|---|---|
mach init | 初始化 .mach 目录和 HOOK | |
mach log | 打开 TUI 仪表盘 | |
mach show | 输出会话的原始 JSON | |
mach push | 推送会话到远程 | |
mach clone | 克隆远程会话 | |
mach pull --repository | 验证并拉取远程仓库元数据 | |
mach verify | 加密验证日志完整性 | |
mach fsck | 重建 SQLite 搜索索引 | |
| `mach config show\ | set` | 查看或修改配置 |
mach fix --apply | 规范化会话记录并重建索引 |
如果需要重新推送某个会话（例如修复后）：mach push 或 mach push 。
实战场景
场景一：Agent 犯错时的回溯
当 Codex 误删了一段逻辑，你不仅想知道最终的结果，还想知道它为什么会做出这个决定。用 mach log 打开 TUI，按 / 搜索被删除的函数名，就能看到 Agent 当时的推理过程——是理解了但手误，还是根本没理解就改了。
场景二：团队 Agent 会话交接
团队中有人用 Claude Code 写出了不错的原型，但你们用的工具不同。他 mach push 后，你用 mach clone 拉下来，直接恢复到他的会话中继续工作——上下文、工具调用历史、文件变更全部保留。
场景三：审计与合规
对于需要满足合规要求的企业团队，mach verify 可以对完整的执行日志进行哈希验证，确保每一步都没有被篡改。结合 mach show 导出的 JSON 原始记录，可以形成可提交的审计报告。
注意事项
- 目前仅支持 终端型 Agent（Claude Code、Codex、Gemini CLI、Copilot CLI 等），IDE 插件（Cursor、VS Code 扩展）暂不支持自动拦截
- 项目使用 Mach License with Restrictions（不允许创建竞争性托管服务或产品）
- 远程操作（push / clone）需要注册 Cognato AI 的云端服务
Mach 解决的是一个几乎所有 AI Agent 重度用户都会遇到、但很少有人系统解决的痛点：Agent 做事不留痕。如果你已经习惯了 git log 来追踪代码变更，那 mach log 可能就是你的下一个必备命令。