Agentpack

Agentpack

为 AI 编码 Agent 提供原生于代码仓库的任务连续性。

Agent 记忆会记住你的工作方式。Agentpack 会记住任务进展到哪里。

你的 Agent 花了一小时处理一项任务。它找到了原因，排除了两种方案，并记下了下一步。随后，上下文被压缩，或者聊天关闭了。下一次会话从零开始，又重复了相同的调查。

Agentpack 将任务状态保存在你的代码仓库中。连接的 Agent 会在工作期间将目标、决策、无效尝试、验证证据和检查点记录到 .agentpack/ 中。之后，下一次会话会加载这些状态并继续：无论是压缩上下文后的同一个 Agent、另一个客户端，还是下周的你。

下面展示了实际运行效果。在会话 1 中，Agent 处理一个不稳定的测试，并通过 Agentpack MCP 工具记录一项决策、一次无效尝试和一个检查点。在会话 2 中，第二天，上下文为空，只需调用一次 load_context，任务状态就会恢复：

▶ 观看 80 秒的讲解视频（含声音）

要在命令行中手动尝试相同的流程，请参阅 docs/DEMOS.md。

• 本地优先。 在你的代码仓库中使用纯文本文件。无需云服务、无遥测、无网络调用。
• 专为 Agent 打造。 本地 MCP 服务和生成的项目说明（AGENTS.md、CLAUDE.md、Cursor 规则）会告知 Agent 何时加载和记录状态。
• 面向用户开放。 CLI 会显示相同的状态，因此你可以自行查看、修正或交接。

这与 Agent 记忆有什么不同？

Claude Code 记忆、Codex 记忆，以及 CLAUDE.md 或 AGENTS.md 记录的是工作方式：你的偏好、项目约定，以及长期有效的信息。Agentpack 记录的是工作进展：当前任务的目标、约束、决策、无效尝试、后续操作和验证结果。

	Agent 记忆	Agentpack
保存内容	偏好、约定、长期有效的信息	单个任务的状态
存储位置	某个客户端的个人资料或账户中	代码仓库中的 .agentpack/，默认保存在本地，也可通过任务包移植
读取者	仅该客户端	任何 MCP 客户端：Claude Code、Codex、Cursor、Claude Desktop
形式	自由格式的笔记，根据相关性回忆	每项任务对应一份 Task Passport：目标、生命周期、可能变更的路径，以及与某次提交绑定的验证
过时情况	不与文件变更关联	关于文件的笔记会保存文件哈希，因此文件变更时 Agentpack 会标记相应笔记

两者可以同时使用。记忆会记录你喜欢的工作方式。Agentpack 会记录任务接下来需要什么。

快速开始

Agentpack 需要 Node.js 20 或更高版本。

npm install -g agentpack-cli

cd path/to/your/repo
agentpack init                     # once per repo
agentpack install claude --write   # per client: codex | claude | cursor | claude-desktop
agentpack install git-hooks --write  # optional: task gate check before each commit

重启或重新连接编码 Agent，并在客户端询问时批准 Agentpack 服务或钩子。从此以后，Agent 会在会话开始时加载任务状态，在工作过程中记录决策和证据，并在有意义的节点创建检查点。

要检查设置，请运行 agentpack doctor。要查看任务状态，请运行 agentpack resume --preset agent --query "<topic>"。

在 Git 仓库中，init 会将本地 Agentpack 文件添加到 .git/info/exclude。列表包括 .agentpack/、.mcp.json、.claude、.codex、.cursor、AGENTS.md 和 CLAUDE.md。Agentpack 不会修改你的 .gitignore。Git 已跟踪的文件仍会保持跟踪状态。

对于每个客户端，docs/INTEGRATIONS.md 说明安装程序会写入哪些内容以及原因。

工作原理

1. 会话开始时，Agent 会加载一份简明摘要：当前的任务护照、近期检查点、决策和来源结论。
2. 工作过程中，Agent 会记录值得保留的内容：决策、失败的方法和验证证据。它还可以记录来源结论：关于某个文件用途的简短说明，并与文件哈希一同保存。如果文件之后发生变化，Agentpack 会标记该结论。哈希匹配只能表明文件未改变，并不能证明结论正确。
3. 在自然停顿时，Agent 会创建一个检查点，其中包含状态、后续操作和 Git 状态。
4. 下一次会话可在任何 MCP 客户端中从该状态继续，而无需根据聊天记录重建任务。

每项任务都有一个任务护照：目标、状态、约束、写入范围（任务可以更改的路径）、后续操作和验证。你可以启动、搁置、切换和完成任务，让每次交接都清晰明确。

任务门控会根据当前护照检查编辑内容。客户端安装程序会为 Claude Code、Codex 和 Cursor 添加原生钩子。install git-hooks 会添加提交前检查。默认情况下，门控只会发出警告。在 .agentpack/config.json 中将 "gateMode" 设为 "block"，即可阻止写入范围以外或当前无活动任务时的编辑；设为 "off" 则会关闭门控。钩子只是防护措施，并非沙箱。参见 docs/CLI.md。

摘要会控制在 token 预算内。Agent 获取的是有用的状态，而不是完整历史记录。

更多功能

• 任务包。 将任务导出到单个 JSON 文件，并在新的克隆仓库或另一台机器上导入。参见 docs/TASK-PASSPORT.md。
• 跨仓库任务。 一个护照可以涵盖多个仓库中的更改，每个仓库都有自己的写入范围。
• 聚焦单体仓库。 为单体仓库的每个部分（api/、frontend/、cron/）创建简短任务，并设置各自的写入范围。Agent 离开该部分时，任务门控会发出警告。
• 用量报告。 agentpack usage report 会读取本地 Claude Code 和 Codex 对话记录，并显示任务的 token 用量，包括 Agentpack 占用的份额。任何内容都不会离开你的机器。
• 只读检查器。 agentpack tui 会在终端中显示任务、证据和检查点。参见 docs/TUI.md。
• 构建器子 Agent。 Codex、Claude Code 和 Cursor 安装版本包含一个用于大型实现工作的可选构建器。主 Agent 会在使用构建器前说明将交接哪些工作。小型任务仍由主 Agent 处理。

适用场景

• 任务进行到一半时，上下文被压缩，而下一轮需要恢复任务状态。
• 任务仍未完成，你却开启了新的聊天。
• 你在 Claude Code、Cursor、Codex 或其他 MCP 客户端之间切换。
• 几天后再回来继续重构或修复 Bug。
• 另一个 Agent 从你的检查点继续工作。

Agentpack 的上下文也会占用 token。精简输出无需保留完整的日志历史，也能让任务状态随时可用。

安全态势

• 零运行时依赖、精确的开发依赖、已提交的锁文件，以及 ignore-scripts=true。
• 常规 CLI 或 MCP 操作不会收集遥测数据，也不会进行网络调用。
• 尽力对已存储上下文和交接输出中看起来像机密的值进行脱敏。
• GitHub Actions 使用 npm provenance（可信发布者，不使用长期有效令牌）发布每个版本。运行 npm audit signatures 进行验证。

完整政策请参阅 SECURITY.md，其中包括 Agentpack 会在仓库外读取哪些内容。

文档

• docs/INTEGRATIONS.md：Codex、Claude Code、Cursor、Claude Desktop 和 Git 钩子的设置
• docs/TASK-PASSPORT.md：任务生命周期、交接、其他仓库和任务包
• docs/CLI.md：完整的 CLI 参考、预算和手动工作流
• docs/MCP.md：MCP 服务协议和工具
• docs/DEMOS.md：可自行运行的简短连续性演示
• docs/TUI.md：只读终端检查器
• docs/LEDGER-HYGIENE.md：保持账本精简实用

贡献

克隆仓库并使用 Node.js 20 或更高版本：

npm ci --ignore-scripts
npm test
npm run mcp:smoke
node dist/src/agentpack.js --help

开发环境设置请参阅 docs/SETUP.md，发布步骤请参阅 docs/RELEASING.md。

---

镜像：Codeberg。问题、版本发布和 npm provenance 均保留在 GitHub 上。