面向 AI 编程助手的 Git checkpoint 工作流工具包。
Agent-Git 用临时 checkpoint 保护任务开始前或阶段之间已有的工作区变更；修改失败时可以回滚，任务完成后可以把连续 checkpoint 和当前未提交变更压缩成一个整洁的正式提交。
项目采用 core + adapters 架构。Git 业务逻辑只存在于 @agent-git/core；CLI 和 MCP 是两种独立的运行时入口，Skill 是可安装的 Agent 工作流说明。
典型工作流如下：
- 使用
status确认分支、工作区变更和待合并 checkpoint。 - 如果当前已有需要保护的未提交变更，使用
save将它们提交为临时 checkpoint。 - 修改代码并验证结果；进入新的高风险阶段前，可以再次保存已有变更。
- 修改失败且明确需要丢弃时，使用
undo回滚。 - 任务完成后先使用
squash --preview检查合并范围，再执行正式squash。
save 保存的是执行命令时已经存在的变更。如果工作区干净，它会跳过 checkpoint；干净仓库的当前 HEAD 已经是可恢复的基线，无需创建空提交。
- 已安装 Git，并且
git命令可用。 - 已安装 Node.js 和
npx。 workspace必须是 Git 仓库中的目录，建议传入仓库根目录的绝对路径。- 执行
undo或压缩 checkpoint 前，建议仓库至少已有一个正常的基础提交。
| 使用场景 | 推荐入口 | 说明 |
|---|---|---|
| 在终端中直接使用 | @agent-git/cli |
命令明确，适合人工调用和脚本。 |
| 使用支持 Skills 的 Agent | @agent-git/skill + CLI |
Skill 指导 Agent 按安全流程调用 CLI。 |
| 使用支持 MCP tools 的 Agent 客户端 | @agent-git/mcp |
客户端通过 stdio MCP Server 调用结构化 tools。 |
| 在项目代码中复用业务逻辑 | @agent-git/core |
内部核心包，不单独发布。 |
Skill 和 MCP 是两种独立入口。同一个工作流步骤不要同时通过 CLI 和 MCP 重复执行。
先查看状态：
npx -y @agent-git/cli@latest status --workspace /path/to/repo如果工作区已有需要保护的变更，创建 checkpoint：
npx -y @agent-git/cli@latest save --workspace /path/to/repo --message "准备继续重构订单流程"任务完成后先预览，再创建正式提交：
npx -y @agent-git/cli@latest squash --workspace /path/to/repo --summary "feat: 重构订单流程" --preview
npx -y @agent-git/cli@latest squash --workspace /path/to/repo --summary "feat: 重构订单流程"Windows PowerShell 示例：
npx -y @agent-git/cli@latest status --workspace "D:\files\project"完整的命令、参数、输出和错误说明参见 @agent-git/cli 文档。
在目标项目根目录执行：
npx -y @agent-git/skill@latest install --target codex安装到所有支持的客户端目录：
npx -y @agent-git/skill@latest install --target all --forceSkill 只安装工作流说明，实际 Git 操作仍通过 Agent-Git CLI 执行。安装目标、覆盖和升级方法参见 @agent-git/skill 文档。
支持 mcpServers 配置的客户端可以使用：
{
"mcpServers": {
"agent-git": {
"command": "npx",
"args": ["-y", "@agent-git/mcp@latest"]
}
}
}配置后可使用 agent-git_status、agent-git_save、agent-git_undo 和 agent-git_squash。完整 schema 和调用示例参见 @agent-git/mcp 文档。
Agent-Git 会真实修改 Git 暂存区和提交历史，执行前请确认操作范围：
save会执行git add .，把整个 workspace 中可暂存的已有变更纳入 checkpoint。save不会创建空提交；工作区干净时会直接跳过。squash --preview不创建正式提交，但当前实现仍会执行git add .，因此可能改变暂存区状态。- 正式
squash会压缩从HEAD开始连续出现的 AI Checkpoint，并把当前未提交变更一并提交。 undo --steps N使用硬重置回退最近 N 个提交，同时丢弃未提交变更；当前实现不会验证这些提交是否都是 AI Checkpoint。- 对已经推送或与他人共享的提交执行
undo或squash可能造成历史分叉，请谨慎使用。
在不确定时，先运行 Agent-Git status，并使用原生 git status、git log 再次核对。
| 包 | 职责 | 文档 |
|---|---|---|
@agent-git/core |
Git checkpoint 工作流的核心业务逻辑。 | README |
@agent-git/mcp |
面向支持 MCP tools 的 Agent 客户端。 | README |
@agent-git/cli |
供 Skill 工作流和终端直接调用。 | README |
@agent-git/skill |
可安装的 Agent-Git 工作流说明。 | README |
@agent-git/typescript-config |
共享 TypeScript 和 tsdown 配置。 | README |
core负责 Git 命令、workspace 校验、checkpoint 识别、回滚和 squash 行为。mcp负责 MCP schema、tool 注册、结果格式化和错误包装。cli负责命令解析、终端输出和退出码。skill负责工作流说明和不同 Agent 客户端的安装路径。typescript-config负责共享 TypeScript 相关配置。
适配层不能复制 core 的 Git 业务逻辑。
pnpm install
pnpm run typecheck
pnpm run lint
pnpm run buildbuild 和 dev 由 Turborepo 编排，包产物会按依赖关系增量构建并缓存。
在本地运行入口：
pnpm --filter @agent-git/cli start -- status --workspace /path/to/repo
pnpm --filter @agent-git/mcp start
pnpm --filter @agent-git/skill start -- install --target codex项目使用 Changesets 管理版本和发布：
pnpm changeset
pnpm version-packages
pnpm release可发布包包括 @agent-git/mcp、@agent-git/cli 和 @agent-git/skill。
内部包不参与发布：
@agent-git/core：构建时被打进 MCP 和 CLI 产物。@agent-git/typescript-config：内部配置包。
MIT