git-tools

Name: git-tools
Author: craft-agent

本地服务

github.com/craft-agent版本控制0今天更新

代码仓库

关于 git-tools

git-tools 为编码 Agent 提供 Git 仓库、提交、变基、工作树和推送工具，并配有指导工具使用的技能。工具按领域划分，工作树和推送工具集可选择启用。

主要功能

01读取仓库状态与提交历史
02暂存、检查并创建提交
03处理变基及堆叠分支
04创建和移除工作树
05预览并安全推送分支

适用场景

01检查工作区状态与冲突
02按仓库规则提交更改
03重整堆叠分支
04隔离并行的工作区
05核对远程分支后推送

MCP 相关

作为 MCP 服务向 MCP 主机提供 Git 工具；默认启用 repo、commit 和 rebase 工具集，worktree 与 push 可选启用。每个工具集配有说明其工具用法的技能。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "craft-agent-git-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/git-tools"
      ]
    }
  }
}

启动命令npx -y @craftsamo/git-tools

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@craftsamo/git-tools0.4.0stdio

工具

收录的工具列表 · 更新于今天

参数	类型	必填	说明
sha	string	否	origin：要读取的提交。
file	string	否	origin：与 lines 一起使用时，指定要 blame 的文件；与 token 或 regex 一起使用时，将搜索范围限制在该文件中；路径相对于工作树根目录。
limit	integer	否	conventions：要抽样的近期非合并提交数量（默认 30）。
lines	string	否	origin："10,20" 或 "10,+5"：要 blame 的范围（返回首行对应的提交）。
paths	array	否	conflicts：仅包含这些冲突文件，路径相对于工作树根目录（默认为全部）。
regex	string	否	origin：查找引入此正则表达式匹配项的提交（git log -G）。
token	string	否	origin：查找引入此精确字符串的提交（git log -S）。
method	enum	是	"status" 读取工作树状态：分支、上游分支、基准、已暂存、未暂存、未跟踪和冲突文件、正在进行的操作、暂存区、工作树以及最近一次 fetch。"conflicts" 读取操作、冲突双方，以及每个冲突文件的标记区域或锁文件重新生成建议。"conventions" 读取提交和拉取请求的约定信号。"origin" 读取某项更改来源的提交。status \| conflicts \| conventions \| origin

详细介绍

git-tools

供编码 Agent 使用的 Git 工具：状态、提交、历史改写与堆叠分支、工作树和推送。

这些工具涵盖任意 Git 远程仓库的工作树状态、提交、历史改写与堆叠分支、工作树和推送。GitHub 上的拉取请求和原生堆叠由 github-tools 提供。工具集列在工具和技能下。

Harness	Delivery	Pinned by
OpenCode V2	原生插件（npm 包，含技能）	包中的版本
OpenCode V1	原生插件（npm 包，不含技能）	包中的版本
Claude Code	插件：MCP 服务和技能	发布标签，作为 ref
Codex	插件：MCP 服务和技能	发布标签，作为 ref
Grok Build	插件：MCP 服务和技能	发布标签，作为 `@ref`
Antigravity	插件：MCP 服务和技能	发布标签的树 URL
Hermes Agent	原生插件（Python，调用命令行）	发布提交，作为 SHA
other MCP host	npm 提供的 MCP 服务	包中的版本

这些工具需要 Node.js 24 或更高版本，以及 git。如果 origin 位于 GitHub 上，一些安全检查也会以你的身份进行身份验证并读取它。 docs/conventions.md 介绍了工具的命名方式和行为。

安装

请从发布版本安装，切勿从默认分支安装：发布版本是一个包含已构建 dist/ 的提交所对应的标签，而默认分支不包含该目录。在下面的命令中，<version> 是发布版本号（1.2.3），<sha> 是该标签指向的提交：

gh api repos/craft-agent/git-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2 在 opencode.json 中接收包和选项：

{
  "plugins": [{ "package": "@craftsamo/git-tools@<version>", "options": { "read_only": false } }],
  "permissions": [{ "action": "git_*", "resource": "*", "effect": "ask" }]
}

OpenCode V1 接收作为字符串的包，或与其选项组成的一对：

{
  "plugin": [["@craftsamo/git-tools@<version>", { "read_only": false }]],
  "permission": { "git_*": "ask" }
}

OpenCode 允许任何没有规则名称的操作，因此除非某条规则指定 ask，否则会静默授予插件请求的权限。读取工具不会请求权限，因此 git_* 通配符是安全的。

启用 worktree 工具集且配置文件不是只读时，V2 插件还会注册一种工作树策略，因此 OpenCode 自带的新建和移除工作树操作也会遵循工作树工具的布局和落地规则：OpenCode 请求使用的名称会成为分支；如果 Git 因文件已更改而拒绝移除，且 Harness 支持，OpenCode 会显示强制操作提示，而工具本身绝不会强制执行。在执行 git_worktree_add 或 git_worktree_remove 后，插件会刷新 OpenCode 的工作树列表，因此更改会立即显示。OpenCode 内置的工作树工具保持原样；可通过权限规则将其关闭。V1 没有工作树策略。

V1 不注册任何技能。解压包并将其中的 skills/* 文件夹复制到 ~/.config/opencode/skills/：

npm pack @craftsamo/git-tools@<version>
tar -xzf craftsamo-git-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-git-tools-<version>.tgz

Claude Code

claude plugin marketplace add craft-agent/git-tools#v<version>
claude plugin install git-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/git-tools --ref v<version>
codex plugin add git-tools@craft-agent

Codex 会将服务器名称中的 - 转换为 _，因此工具会显示为 mcp__git_tools__git_*。它会在插件的安装目录中启动 MCP 服务，该目录绝不会是调用方的工作树。

Grok Build

grok plugin install craft-agent/git-tools@v<version> --trust

Grok 会在会话的工作目录中启动 MCP 服务。

Antigravity

请从发布标签对应的树安装，切勿从默认分支安装，因为默认分支没有已构建的 dist/；Antigravity 会将该标签克隆到 ~/.gemini/config/plugins/git-tools。

agy plugin install https://github.com/craft-agent/git-tools/tree/v<version>

Hermes Agent

Hermes 安装的是一个提交，而不是标签，并且插件默认处于禁用状态：

hermes plugins install craft-agent/git-tools --ref <sha>
hermes plugins enable git-tools

如果 Hermes 网关已在运行，请重启它（hermes gateway restart），以加载插件。

插件会运行 Hermes 启动时找到的 Node。如果版本管理器在 Hermes 运行期间移除了该版本，调用时会重新查找 Node；如果找不到，请在 node 可运行的 shell 中重启 Hermes。

其他 MCP 主机

将服务添加到主机的 MCP 配置中。标志放在 args 中：

{
  "mcpServers": {
    "git-tools": {
      "command": "npx",
      "args": ["-y", "@craftsamo/git-tools@<version>", "--read-only"]
    }
  }
}

工具和技能

每个工具集都附带一项技能，告诉 Agent 如何使用其中的工具。每个领域对应一个工具集；repo、commit 和 rebase 默认启用，worktree 和 push 则需选择启用。

技能会在其 frontmatter 的 metadata 下声明所属工具集（metadata: { toolset: commit }，以块的形式书写）。OpenCode V2 和 Hermes 只有在设置启用了该工具集的至少一个工具时才会注册该技能，因此，关闭工具集或移除了其中所有工具的配置不会显示该技能；未指定工具集的技能始终会注册。Claude Code、Codex、Grok Build 和 Antigravity 会安装整个技能文件夹，并且只将设置传递给 MCP 服务，因此无论设置选择了哪些工具集，它们都会列出所有技能。OpenCode V1 不会注册技能，而且也会列出所有复制过去的技能。

工具集	涵盖内容
`repo`	本地读取：状态、历史记录、更改的来源、冲突
`commit`	暂存、提交前检查、提交、修改提交和修正提交
`rebase`	变基、一起变基的堆叠分支，以及重写规则
`worktree`	创建、列出和移除工作树
`push`	推送一个或多个分支，并与每个分支预期的远程提交进行比较

`repo`

一个只读工具，不会更改任何内容，也不会访问远程服务。git-repo 技能会说明何时使用每种方法。

工具	方法	读取内容
`git_repo_read`	`status`	分支及其上游分支、与远程默认分支的比较状态、按状态分类的文件、正在进行的操作、贮藏、工作树、上次获取时间
	`conflicts`	合并、变基、挑选提交或还原操作留下的内容：冲突双方，以及每个冲突文件的标记区域或其锁文件命令
	`conventions`	最近提交的主题及其约定式类型和作用域，以及工作树中的提交配置文件和拉取请求模板
	`origin`	通过 sha、blame 或 pickaxe 查找更改的来源提交，并显示其完整消息

`commit`

一个用于提交前检查的读取工具，以及四个写入工具。 git-commit 技能说明了它们如何配合使用。

工具	类别	功能
`git_commit_read`	读取	`lint`：根据通用规则和仓库的 commitlint 检查候选提交消息；`secrets`：检查暂存更改、未暂存更改或指定范围内的凭据；`hunks`：获取带有差异摘要的未暂存代码块；`amend`：判断应通过 amend、fixup 还是新提交来修正提交
`git_commit_stage`	幂等更改	根据列表的摘要暂存其中的代码块
`git_commit_create`	添加	使用经过检查的消息提交已暂存内容，或创建对较早提交的 fixup
`git_commit_amend`	覆盖	按照重写提交的规则，用已暂存更改和消息替换 HEAD
`git_commit_verify`	管理性	在一次性工作树中的分支每个提交上运行命令

`rebase`

一个用于读取已检出分支的提交栈的读取工具，以及三个写入工具。提交栈根据祖先关系读取，因此单个分支就是只有一层的提交栈。 git-rebase 技能说明了它们如何配合使用。

工具	类别	功能
`git_rebase_read`	读取	`stack`：按从底到顶的顺序列出分支线上的各层及其提交和 fixup、每层相对于远程分支的状态，以及整个提交栈是否可以重写
`git_rebase_start`	覆盖	按照重写提交的规则，将每层变基到最新的默认分支，或就地合并 fixup；遇到冲突时会暂停并返回暂停状态
`git_rebase_resume`	覆盖	继续、跳过或中止已暂停的变基
`git_rebase_split`	添加	在指定提交处将分支拆分为较低层的分支，或在顶部添加一个空层

`worktree`

一个用于列出工作树的只读工具，以及两个写入工具：一个按布局添加工作树，另一个在不丢失工作的情况下移除工作树。该工具集需选择启用。git-worktree 技能说明了它们如何配合使用，布局见设置。

工具	类别	功能
`git_worktree_read`	读取	`list`：仅通过 git 列出仓库的所有工作树：目录、分支和提交，是否为主工作树或调用者所在的工作树，是否已锁定或已消失，以及是否位于布局指定的位置
`git_worktree_add`	添加	为分支在 `<root>/<repository>/<branch>` 处添加工作树：使用现有分支原样创建，或从 `from` 切出新分支，否则从 origin 已获取的默认分支创建；不设置上游，也不在检出时运行钩子
`git_worktree_remove`	覆盖	移除工作树，绝不强制执行：遇到已更改的文件、无引用保护的提交或正在进行的操作时会拒绝；仅在确认分支已合并后（通过祖先关系或 GitHub 上已合并的拉取请求）才删除分支，并说明保留分支的原因

`push`

一个用于预览推送的只读工具，以及一个写入工具，用于按预览返回的内容推送，并基于远程各分支预期的提交进行租约检查。该工具集需选择启用。git-push 技能说明了它们如何配合使用。

工具	类别	功能
`git_push_read`	读取	`preview`：逐个分支从远程实时读取，显示推送类型、远程缺少的提交以及强制推送会丢弃的内容；拒绝原因、警告、密钥扫描和已发布文本规则；以及 `send`，即精确执行此次推送所需的参数
`git_push_send`	管理	在再次检查后，通过一次原子推送并为每个分支设置租约，推送预览中的 `send`；如果分支或远程已发生变化，则会标记为 `stale`，且不会推送任何内容

添加工具

使用 defineTool 在 src/core/<domain>/<verb>.ts 中编写规范：包括 ID <prefix>_<domain>_<verb>、标题和描述、Zod 参数和输出架构、所属工具集和写入类别，以及 execute(args, context)。写入工具还需提供 targets(args, context)：说明调用会写入什么，权限规则应以此为目标。
在规范旁边测试工具（<verb>.test.ts），像各入口点一样通过 invoke 调用。运行程序的工具应针对 PATH 中该程序的伪实现进行测试；没有测试会连接真实服务。
在 src/tools.ts 中列出工具。新增工具集时，将其加入 src/project.ts 中的 toolsets（如果默认启用，也加入 defaultToolsets）；如果工具读取了设置之外的变量，也将其加入 toolVariables。
添加或更新工具集的 skill：skills/<prefix>-<toolset>/SKILL.md，其 frontmatter 应在 metadata 下声明该工具集。
运行 pnpm run build && pnpm run manifests，将工具列入 plugin.yaml，并将其变量列入 Codex 的清单，然后在 “工具和 skills”下介绍它。

docs/conventions.md 说明了每个步骤所遵循的规则。

读取与写入

每个读取工具都命名为 <prefix>_<domain>_read。读取操作可以在未询问的情况下运行；写入操作由执行框架确认。

执行框架	无需询问即可读取
OpenCode	始终可以；插件只会在写入前询问
Claude Code	`~/.claude/settings.json` 中 `permissions.allow` 下的规则 `mcp__plugin_git-tools_git-tools__*_read`
Codex	始终可以；Codex 会在未询问的情况下运行声明了 `readOnlyHint` 的工具，读取工具就是如此
Grok Build	`grok --allow 'MCPTool(git-tools___read)' --allow 'MCPTool(git__read)'`（两条规则；见下文）
Antigravity	`permissions.allow` 中的规则 `mcp(git-tools_git-tools/<tool id>)`，每个读取工具各一条
Hermes	始终可以；插件只会在写入前询问

关于何时会询问写入操作，何时不会：

OpenCode 不需要规则名称即可授予任何操作权限，因此写入操作会在未询问的情况下运行，除非有规则要求确认：添加 OpenCode 下所示的 git_* 规则。
Codex 在 codex exec 模式下，以及 Grok Build 在 grok -p 模式下，会拒绝无法询问确认的写入操作，除非事先已获准。
Grok Build 通过 use_tool 工具调用插件工具，且 Agent 通常会先省略服务名称来指定工具。 Grok 会根据给出的名称检查规则，因此仅有包含服务名称的规则无法匹配第一次调用。第二条规则会匹配简短名称；但写入操作仍无法匹配任何一条规则。
Antigravity 会在任何 MCP 工具调用前询问，除非规则已允许该工具；读取操作也包括在内。它将插件的服务命名为 git-tools_git-tools（先是插件，然后是服务）。 agy -p 会拒绝无法询问确认的工具。
Hermes 的 hermes chat -q 会拒绝无法询问确认的写入操作；hermes -z 和 --yolo 会跳过审批，因此写入操作随后会在未询问的情况下运行。

设置

每个入口点使用相同的设置。命令行标志优先于其环境变量；选项或设置也优先于该变量。

Setting	Flag	Variable	Meaning
`toolsets`	`--toolsets`	`GIT_TOOLS_TOOLSETS`	已启用的工具集，或 `all`；默认启用 `src/project.ts` 中列出的名称
`read_only`	`--read-only`	`GIT_TOOLS_READ_ONLY`	不注册任何会写入的工具；优先级高于其他所有设置
`tools`	`--tools`	`GIT_TOOLS_TOOLS`	按 ID 添加单个工具，不受其所属工具集限制
`exclude_tools`	`--exclude-tools`	`GIT_TOOLS_EXCLUDE_TOOLS`	按 ID 移除单个工具；优先级高于 `tools` 和 `toolsets`
`confirm`	`--confirm`	`GIT_TOOLS_CONFIRM`	仅适用于 MCP 服务：根据约定，可设为 `harness`（默认）或 `elicitation`
`language`	`--language`	`GIT_TOOLS_LANGUAGE`	仅适用于原生插件：审批提示词使用的语言，例如 `ja`
`emoji`	—	—	仅适用于 Hermes：按工具集名称指定显示在每个工具集旁的表情符号（留空 `""` 表示不显示）
`published_text_rules`	`--published-text-rules`	`GIT_TOOLS_PUBLISHED_TEXT_RULES`	包含已发布文本规则的 JSON 文件绝对路径（参见 push 工具集）；未设置时不进行检查
`worktree_root`	`--worktree-root`	`GIT_TOOLS_WORKTREE_ROOT`	任务工作树的存放绝对路径（允许使用 `~`）；未设置时为 `~/worktrees`

列表在标志或变量中以逗号分隔。published_text_rules 和 worktree_root 用于存放文本，会先去除首尾空白；留空表示未设置，并由工具自行读取；插件选项和 Hermes 设置使用相同名称。目录结构为 <root>/<repository>/<branch>，分支中的每个 / 都会替换为 -；repository 取 origin URL 的最后一部分并去掉 .git，否则使用主检出目录的文件夹名称。各运行环境读取这些设置的方式如下：

OpenCode 使用上面所示的插件 options，列表以数组表示， read_only 为布尔值；若未提供，则回退到环境变量。V2 在后台服务中运行插件，该服务会保留启动时的环境：在启动 opencode run 的环境中设置变量后，需要在该环境中重启服务（opencode service restart），设置才会生效。V1 在自身进程中运行插件。
Hermes 使用 config.yaml 中的 plugins.entries.git-tools.settings：
```
plugins:
  entries:
    git-tools:
      settings:
        read_only: false
        exclude_tools: []
        published_text_rules: /home/me/.config/git-tools/published-text.json
        worktree_root: ~/worktrees
```
若未设置 language，审批卡片会使用 Hermes 自身的 display.language（或 HERMES_LANGUAGE），即审批按钮的语言；否则使用英语。插件会将自身的环境传递给运行的命令行，因此环境变量也有效。运行中的网关会保留启动时的环境；更改环境变量后，请重启网关（hermes gateway restart）。
Claude Code、Grok Build 和 Antigravity 不带标志地启动插件的服务器，并将客户端的环境传递给它，因此请在运行工作台的环境中设置这些变量。
Codex 只会向插件的 MCP 服务传递少数基本变量（例如 PATH 和 HOME）以及插件清单中列出的变量，也就是上述变量：请在运行 Codex 的环境中设置它们。工具除设置项之外读取的变量应放在 src/project.ts 的 toolVariables 中；pnpm run manifests 会在设置项的变量之后将其添加到清单中。若要传递标志，或向服务器提供软件包未列出的变量，请在 Codex 的 config.toml 中的 [mcp_servers] 下添加该服务器，而不要使用插件：标志放在 args 中，env_vars 用于指定要从 Codex 环境转发的变量，env 用于设置固定值。
```
[mcp_servers.git-tools]
command = "npx"
args = ["-y", "@craftsamo/git-tools@<version>", "--read-only"]
env_vars = ["GIT_TOOLS_TOOLSETS"]
```

目录结构

src/project.ts — 软件包名称、工具 ID 前缀、设置项前缀、工具集，以及工具读取的其他变量。
src/core/ — 工具契约和工具，不包含任何工作台相关内容或项目名称。
src/tools.ts — 所有工具的列表，每个入口点都会注册这些工具。
src/words.ts — 各语言版本的工具用语翻译，原生插件会在其审批提示词中使用这些内容。
src/mcp/ — MCP 服务，构建为 dist/mcp.js，并由 git-tools 运行。
src/opencode/ — OpenCode 插件，构建为 dist/opencode.js。
src/cli/ — Hermes 插件调用的命令行程序，构建为 dist/cli.js，并由 git-tools-cli 运行。
src/hermes/、plugin.yaml 和 __init__.py — Hermes 插件。
skills/ — 每个工具集对应一个技能，位于 skills/<name>/SKILL.md。所有支持技能的工作台都会从软件包或插件根目录加载技能；原生插件只加载已启用工具集的技能。
.claude-plugin/、.codex-plugin/、.agents/plugins/、.mcp.json、.antigravity-plugin/ 和 mcp_config.json — 其他工作台的插件清单。Codex 会读取 .codex-plugin/plugin.json；根目录中的 plugin.json 会使其将插件作为 Agent Plugin 加载，而其工具预算会隐藏超过固定数量的工具。根目录的 .mcp.json 是 Grok Build 读取的配置（其中使用 ${CLAUDE_PLUGIN_ROOT}，这是 Grok Build 和 Claude Code 都会展开的变量）；在 Claude Code 中处理此仓库时，请拒绝它通过该文件提供的项目 MCP 服务。
opencode.jsonc — 用于在此仓库中工作的 OpenCode 配置，不属于软件包的一部分：它引用了创建此配置所基于的 starter 和 github-tools，使 Agent 能够在此代码旁读取它们。

发布流程见 RELEASING.md。

许可证

AGPL-3.0 with Commons Clause

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

git-tools

关于 git-tools

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

git-tools

安装

OpenCode

Claude Code

Codex

Grok Build

Antigravity

Hermes Agent

其他 MCP 主机

工具和技能

repo

commit

rebase

worktree

push

添加工具

读取与写入

设置

目录结构

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

`repo`

`commit`

`rebase`

`worktree`

`push`