Githits

GitHits CLI

连接 Agent 与开源生态的基础设施层。

网站 · 文档 · 问题反馈

GitHits 将 AI 编码 Agent 与覆盖完整软件开发生命周期的公开开源证据连接起来，包括发现、规划、研究、实现、调试和维护。

CLI 会运行一个本地 MCP 服务，你的编码工具会按需启动该服务。随后，Agent 可以搜索已编入索引的包和仓库源代码、读取特定文件和文档页面、检查包的健康状况、比较依赖升级，并从真实开源项目中查找附有源代码引用的示例。当大模型知识和本地仓库上下文不足以解决问题时，这些功能就能派上用场。

想要在 Agent 工具链或软件工厂中使用 GitHits？请查看我们的公开 API 文档。

快速开始

npx githits@latest init

init 会为你登录、检测受支持的编码工具，并为你选中的工具配置 GitHits。除 Cursor 外，它使用本地 stdio MCP；Cursor 的直接配置使用托管的远程 MCP。

自动配置目前支持 Claude Code、Cursor、Windsurf、VS Code / Copilot、Cline、Claude Desktop、Codex CLI、Pi、Gemini CLI、Google Antigravity、OpenCode、Hermes Agent、Zed、Junie、Qwen Code、Kiro、Kilo Code、Factory Droid 和 Amazon Q CLI。

配置完成后，打开编码 Agent 并照常工作。许多 Agent 需要有源代码依据的上下文时会调用 GitHits。如果 Agent 开始猜测，请直接提示它：

Use GitHits Code Navigation to inspect npm:express. Find how middleware
errors are handled, read the relevant source, and explain the fix before
editing code.

GitHits 的新增功能

GitHits 面向这样的场景：Agent 需要从更广泛的开源生态中获取证据，而不只是依赖模型记忆或本地仓库上下文：

能力	MCP 工具	CLI 命令
工具导航	quick_start	—
代码示例	get_example	githits example
浏览清单	list	githits list
搜索代码和文档	search, search_status, grep	githits search, githits search-status, githits grep
阅读源文件或文档章节	read	githits read <target> [path]
包检查	pkg_info, pkg_vulns, pkg_deps, pkg_changelog, pkg_upgrade_review	githits pkg ...

当 Agent 需要以下操作时，请使用 GitHits：

• 了解、规划或研究开源项目如何解决模糊问题或陌生错误
• 在各个仓库中寻找广泛的先例，或大海捞针般的稀有示例
• 检查已知包或仓库中的源代码、测试、符号或文档
• 在更改代码前，验证依赖项的实际行为
• 调试指向第三方代码的堆栈跟踪
• 审查包的健康状况、许可证、漏洞、依赖项和变更日志
• 使用事实证据比较依赖项升级

示例

在开源项目中寻找先例：

npx githits@latest example "HTTP retries with exponential backoff in Python"

搜索依赖项的索引代码、文档和符号：

npx githits@latest search "router middleware" --in npm:express
npx githits@latest search '"body parser" OR multer' --in npm:express --source docs
npx githits@latest search "debounce" --in npm:lodash --source symbol

无需克隆即可读取和 grep 依赖项源代码：

npx githits@latest code files npm:express lib
npx githits@latest code read npm:express lib/router/index.js --lines 120-200
npx githits@latest grep 'router\.use' npm:express --path-prefix lib/

检查包的健康状况和升级证据：

npx githits@latest pkg info npm:express
npx githits@latest pkg vulns npm:[email protected] --severity high
npx githits@latest pkg deps npm:[email protected] --depth 2
npx githits@latest pkg changelog npm:express --from 4.18.2 --to 5.2.1
npx githits@latest pkg upgrade-review npm:[email protected] --to 4.4.3

浏览并阅读包文档：

npx githits@latest docs list npm:express
npx githits@latest docs read <docs-read-target> --lines 20-80

源代码差异

githits code diff 和公开 MCP code_diff 工具默认可用。 比较特定包版本或公开仓库引用，例如：

githits code diff npm:express 5.2.0..5.2.1 --stat
githits code diff npm:express 5.2.0..5.2.1 --patch -- 'lib/**/*.js'

除非使用明确的路径 glob 缩小范围，否则包差异覆盖整个仓库。 原始差异无法证明升级安全。有关范围、补丁安全性和支持的寻址方式，请参阅源代码差异。 托管 MCP 的可用性要求采用已发布的 @githits/mcp 包并完成部署。

目标解析

resolve_target / githits resolve 可将模糊、拼写错误或有歧义的公开包、仓库或文档站点名称转换为按排名排列的规范目标。 它默认可在 CLI、本地 MCP 和公开 MCP 包中使用。 规范目标会跳过解析；身份不确定时需要明确选择。 有关后续规则和限制，请参阅目标解析。 采用已发布的包并完成部署后，托管 MCP 和插件即可使用此功能。

研究

research / githits research 可针对某个公开包或仓库回答问题，并提供引用来源的已验证答案。它默认可在 CLI、本地 MCP 和公开 MCP 包中使用：

githits research "How does FastAPI dependency injection resolve nested dependencies?"
githits research npm:express "Where is router dispatch implemented?"
githits research --thread <thread-id> "How does that interact with route parameters?"

省略目标后，GitHits 会根据问题识别目标；后续提问可复用返回的线程 ID。答案通常需要 30 秒到几分钟。问题会发送给 GitHits，因此切勿包含凭据、个人数据或私有代码。研究可能返回速率限制或每日限制错误；消息会说明何时可以重试，每日限制于 00:00 UTC 重置。有关来源、线程和限制，请参阅研究。 采用已发布的包并完成部署后，托管 MCP 和插件即可使用此功能。

支持的来源

GitHits 支持包和仓库目标，例如：

• 包规格：npm:react、npm:[email protected]、pypi:requests、crates:serde
• GitHub 仓库：https://github.com/expressjs/express、github:expressjs/express@main

包检查支持 npm、PyPI、Hex、Crates、NuGet、Maven、Packagist、RubyGems、Go、Swift、vcpkg 和 Zig。vcpkg 和 Zig 不提供公告数据；依赖关系图支持因注册表而异。cargo: 是 crates:（公开 crates.io）的输入别名；规范注册表标识仍为 crates。

许可证筛选

代码示例搜索支持许可证筛选：

• strict 是默认选项，会筛除采用 copyleft 许可证或未声明许可证的仓库
• custom 使用你在 githits.com 配置的账号屏蔽列表
• yolo 会停用许可证筛选

npx githits@latest example "async file reading" --lang python --license strict

身份验证

常规本地设置通过以下命令完成：

npx githits@latest init

手动登录：

npx githits@latest login

建议在本地开发时使用浏览器 OAuth。凭据默认存储在系统钥匙串中，并会自动刷新。常用标志：

• init --no-browser 或 login --no-browser 会打印登录 URL，而不启动浏览器
• init --port <port> 或 login --port <port> 会固定环回回调端口
• login --force 即使你已登录，也会重新进行身份验证

OAuth 回调始终在运行 GitHits 的机器上监听。当 GitHits 通过 SSH 运行，而浏览器在本地运行时，请从浏览器所在机器转发所选端口：

ssh -N -L 8765:127.0.0.1:8765 user@remote-host

隧道建立后，在远程机器上使用相同端口运行 GitHits：

npx githits@latest init --no-browser --port 8765

在本地浏览器中打开 GitHits 打印的 URL。将 user@remote-host 替换为你通常使用的 SSH 目标地址。完成设置后，githits login 也可以使用相同的标志。

浏览器 OAuth 需要交互操作。对于 CI 和其他无人值守环境，请通过环境的密钥管理器提供 GITHITS_API_TOKEN。

钥匙串提示与文件存储

GitHits 默认使用系统钥匙串，因为 OAuth 凭据包含刷新令牌。在 macOS 上，这指的是“钥匙串访问”；在 Windows 上，这指的是“凭据管理器”；在 Linux 上，这指的是可用的 Secret Service 或密钥环后端。

如果 macOS 显示类似“githits 想要访问……钥匙串中的项目”的提示，并且你信任已安装的 githits CLI，请选择 始终允许。GitHits 无法自定义此操作系统提示；该提示由 macOS 生成。

GitHits 还会写入一个不含机密的小型元数据文件，因此最近的启动检查无需读取钥匙串。只有 GitHits 需要令牌时才会读取钥匙串，例如调用工具、刷新令牌、运行 githits auth status，或在元数据过期或失效后检查登录状态时。

如果即使选择了 始终允许，你的 Agent 仍不断显示钥匙串提示，请将 OAuth 存储切换为文件模式：

# macOS/Linux: ~/.config/githits/config.toml, or $XDG_CONFIG_HOME/githits/config.toml
# Windows: %APPDATA%\githits\config.toml
[auth]
storage = "file"

在创建 config.toml 或 GitHits 写入身份验证元数据之前，配置目录可能为空。较早的 macOS 安装可能使用过 ~/Library/Application Support/githits；GitHits 仍会读取该位置以进行迁移，但新的身份验证配置和文件存储使用 ~/.config/githits。

你也可以选择仅对单个进程启用该模式：

GITHITS_AUTH_STORAGE=file githits login --force

文件模式会将 OAuth 凭据以 JSON 文件形式存储在 GitHits 配置目录下。在平台支持的情况下，这些文件会以私有权限写入，但不会加密。任何能够以你的操作系统用户身份读取文件的进程，都可能读取令牌。

仅在你信任本地用户账户访问权限的机器上使用文件模式。对于 CI 和自动化，建议使用 GITHITS_API_TOKEN，而不是浏览器 OAuth。

使用以下命令检查身份验证和运行时状态：

npx githits@latest auth status
npx githits@latest doctor

请参阅身份验证文档，了解钥匙串行为、文件存储模式、CI 设置和故障排查。

手动设置 MCP

如果你的编码工具未由 init 自动配置，请手动将 GitHits 添加到其 MCP 配置中：

{
  "mcpServers": {
    "githits": {
      "command": "npx",
      "args": ["-y", "githits@latest", "mcp", "start"]
    }
  }
}

你的工具会通过标准输入/输出运行此命令。无需后台守护进程或全局安装。

删除由 init 写入的配置：

npx githits@latest uninstall

此操作会移除由 init 写入的 GitHits MCP 配置和指引，同时保留已存储的凭据。运行 npx githits@latest logout 可单独移除凭据。兼容命令 npx githits@latest init uninstall 接受相同的 --yes、--project 和 --keep-guidance 选项。

项目设置

如需配置项目本地 MCP，请运行：

npx githits@latest init --project

仅支持已验证的项目本地 MCP 工具才可进行项目设置。项目配置不包含机密信息，但可能像其他工具配置一样提交，因此请先检查生成的文件，再将其添加到源代码管理中。

面向 Agent 的安全非交互式设置会分阶段发现并明确安装：

npx githits@latest init --detect-agents --json
npx githits@latest init --install-agents cursor,codex-cli

插件和扩展打包

此仓库和已发布的软件包提供兼容宿主所需的插件和扩展资源。通过 Git 安装时，也会保留上下文文件符号链接（CLAUDE.md 和 GEMINI.md），它们指向规范文件 AGENTS.md：

• .plugin/plugin.json
• .claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• .codex-plugin/plugin.json
• .cursor-plugin/plugin.json
• .mcp.json
• gemini-extension.json
• plugin.json（Google Antigravity）
• mcp_config.json（Google Antigravity）
• AGENTS.md
• CLAUDE.md
• GEMINI.md
• skills/

根目录的技能树供所有受支持的宿主共用。所有插件和扩展安装都会使用托管的远程 MCP，包括 Claude、Codex、Cursor、Gemini CLI、Google Antigravity 和 VS Code/GitHub Copilot OpenPlugin。直接运行 githits init 是另一种设置方式：它会为受支持的工具安装本地 stdio 配置，但 Cursor 除外，它仍仅支持远程方式。通过 plugin.json、mcp_config.json 和共用的 skills/ 树，仓库根目录可作为原生 Antigravity 插件使用。使用 bun run plugins:generate 刷新生成的清单，并使用 bun run plugins:check 进行验证。

引导式 init 仅为所选 Agent 安装四个规范技能（githits-code、githits-mcp、githits-onboarding 和 githits-package）。支持共用技能的 Agent 在用户级别使用 ~/.agents/skills/，或在项目级别使用 .agents/skills/；仅支持原生技能的 Agent 则使用经过验证的原生技能目录。能够读取共用根目录的兼容 Agent 可以发现这些技能。之后再次运行引导式设置会修复缺失的技能；迁移操作仅会在验证完整的共用技能集后，移除历史遗留的 Cline 或 Junie githits-mcp/SKILL.md。

如需通过 Claude Code marketplace 安装：

claude plugin marketplace add githits-com/githits-cli
claude plugin install githits@githits-plugins

如需安装 Gemini CLI 扩展：

gemini extensions install https://github.com/githits-com/githits-cli

命令参考

githits init             Connect GitHits to your coding agents
githits uninstall        Remove GitHits MCP configuration and guidance
githits init uninstall   Compatibility alias for `githits uninstall`
githits login            Sign in to your GitHits account
githits logout           Remove stored credentials
githits mcp              Show setup instructions or start the local MCP server
githits mcp start        Always start the local MCP server over stdio
githits example          Find real-world implementations from open source
githits doctor           Diagnose configuration and auth state
githits resolve          Resolve a fuzzy name to canonical targets
githits settings         View and update preferences, privacy, and terms
githits search           Explore repository code, dependencies, docs, and symbols
githits search-status    Check the status of a previous indexed search
githits code             List, read, grep, or diff source
githits pkg              Inspect package metadata, vulnerabilities, deps, and changelogs
githits docs             Browse and read package documentation
githits auth             Manage authentication
githits auth status      Show authentication status

完整 CLI 参考：https://docs.githits.com/cli/commands

环境变量

大多数用户无需设置环境变量。以下是 CI、身份验证存储和本地诊断常用的覆盖项：

变量	用途	默认值
GITHITS_API_TOKEN	用于身份验证的 API 令牌	未设置
GITHITS_AUTH_STORAGE	覆盖 OAuth 存储模式：keychain 或 file	keychain
GITHITS_DISABLE_UPDATE_CHECK	禁用 npm 最新版本更新通知	未设置
GITHITS_TELEMETRY	将本地计时诊断信息输出到 stderr	未设置

完整参考：https://docs.githits.com/cli/environment-variables

源代码布局

此仓库包含 GitHits CLI 和可复用的 MCP 软件包：

• src/ - CLI 命令、本地身份验证、设置流程和本地 MCP stdio 启动
• packages/mcp/ - 面向传输方式无关的 MCP 服务 API、工具注册、说明和冒烟测试辅助工具的公共 @githits/mcp 软件包
• packages/core-internal/ - CLI 和 MCP 软件包共用的工作区实现
• docs/ - 实现说明和贡献者指南
• scripts/ - 软件包验证、冒烟测试和开发工具

已发布的变更、待处理工作和当前软件包版本影响，请参阅 CHANGELOG.md。

开发

要求：

• Node.js ^20.18.1 || >=22.13.0
• Bun
• 运行依赖升级评分器测试需要 Python 3.11 或更高版本（Windows 上使用 python，其他平台使用 python3）

常用命令：

bun install
bun run dev --help
bun test
bun run typecheck
bun run build

修改 MCP 工具、CLI 命令、共享格式化器、身份验证／错误封装或 MCP/CLI 一致性行为时，也请运行相关的冒烟测试套件：

bun run smoke:mcp
bun run smoke:cli

CI 还会在没有凭据且不调用在线后端的情况下检查构建产物。运行 bun run build 后，请在本地执行相同的检查：

bun run smoke:cli:built
bun run smoke:mcp:built

测试框架仍使用 Bun，而产品子进程会使用 PATH 中的 node 执行 dist/cli.js。CI 会根据 .node-version 配置该运行时。

密钥扫描使用 8.30.1 版 gitleaks OSS CLI。pre-commit 钩子会对已暂存的更改运行 bun run check:gitleaks。在本地扫描完整历史记录：

gitleaks git --redact --no-banner --no-color .

从 gitleaks releases 安装 8.30.1 版二进制文件，并将其放入 PATH。有关 CI 计划、抑制规则顺序和 npm 包边界，请参阅密钥扫描。

修改 MCP 指令、工具描述或面向 Agent 的行为时，请使用 eval/agentic/README.md 中介绍的针对性 Agent 评估：

bun run agent:e2e

许可证

Apache-2.0