Entire CLI

Entire 可以无缝集成到你的 Git 工作流中，在你编写代码的过程中捕获 AI 代理会话。这些会话会与提交记录一同索引，从而在你的仓库中创建一个可搜索的代码编写过程记录。

使用 Entire，你可以：

• 了解代码变更的原因 — 查看完整的提示/响应对话记录以及被修改的文件
• 即时恢复 — 当代理行为异常时，回退到已知良好的检查点并无缝继续工作
• 保持 Git 历史整洁 — 将代理上下文保存在单独的分支上
• 更快地完成入职培训 — 展示从提示 → 变更 → 提交的完整路径
• 确保可追溯性 — 在需要时支持审计和合规要求

为什么选择 Entire

• 理解代码为何变更，而不仅仅是变更了什么 — 每次提交都会伴随对话记录、提示内容、涉及的文件、令牌使用情况、工具调用等信息一起被捕获。
• 从任意检查点回退并恢复 — 随时返回之前的代理会话，并从中断的地方继续工作。
• 完整上下文保存且可搜索 — 每次 AI 交互都会生成版本化的记录，并与你的 Git 历史绑定，不会丢失任何信息。
• 无需切换上下文 — 原生支持 Git，两步即可完成设置，兼容 Claude Code、Codex、Gemini 等多种模型。

目录

• 为什么选择 Entire
• 快速入门
• 典型工作流程
• 核心概念
  • 工作原理
  • 策略
• 本地设备认证测试
• 命令参考
• 配置
• 安全与隐私
• 故障排除
• 开发
• 获取帮助
• 许可证

系统要求

• Git
• macOS、Linux 或 Windows
• 已安装并认证的支持的代理

快速入门

# 通过 Homebrew 安装
brew tap entireio/tap
brew install entireio/tap/entire

# 或通过 Scoop（Windows）安装
scoop bucket add entire https://github.com/entireio/scoop-bucket.git
scoop install entire/cli

# 或通过 Go 安装
go install github.com/entireio/cli/cmd/entire@latest

# Linux：将 Go 二进制文件添加到 PATH（如果尚未配置，请添加到 ~/.zshrc 或 ~/.bashrc）
export PATH="$HOME/go/bin:$PATH"

# 在项目中启用
cd your-project && entire enable

# 检查状态
entire status

典型工作流程

1. 在你的仓库中启用 Entire

entire enable

此命令会安装代理和 Git 钩子，以便与你的 AI 代理协同工作。系统会提示你选择要启用的代理。若需非交互式地启用特定代理，可以使用 entire enable --agent <name>（例如 entire enable --agent cursor）。

钩子会在你工作时捕获会话数据。当你或代理执行 Git 提交时，会创建检查点。你的代码提交将保持干净，Entire 不会在你的当前分支上创建任何提交。所有会话元数据都将存储在名为 entire/checkpoints/v1 的独立分支上。

2. 使用你的 AI 代理

只需像往常一样使用你的 AI 代理即可。Entire 会在后台运行，跟踪你的会话：

entire status  # 随时查看当前会话状态

3. 回退到之前的检查点

如果你想撤销部分更改并回到之前的检查点：

entire rewind

此命令会显示当前会话中的所有可用检查点。选择其中一个，即可将代码恢复到该状态。

4. 恢复之前的会话

要为某个分支恢复最新的检查点会话元数据：

entire resume <branch>

Entire 会检出该分支，恢复最新的检查点会话元数据（可能包含一个或多个会话），并输出继续工作的命令。

5. 禁用 Entire（可选）

entire disable

此命令会移除 Git 钩子。你的代码和提交历史将不受影响。

核心概念

会话

会话 表示与 AI 代理从开始到结束的完整交互过程。每个会话会记录所有的提示、响应、修改的文件以及时间戳。

会话 ID 格式： YYYY-MM-DD-<UUID>（例如 2026-01-08-abc123de-f456-7890-abcd-ef1234567890）

会话数据与你的代码提交分开存储在 entire/checkpoints/v1 分支上。

检查点

检查点 是会话中的一个快照，你可以回退到它——相当于工作中的“存档点”。

当您或代理执行 Git 提交时，会创建检查点。检查点 ID 是一个 12 位的十六进制字符串（例如 a3b2c4d5e6f7）。

工作原理

您的分支                    entire/checkpoints/v1
     │                                  │
     ▼                                  │
[基础提交]                           │
     │                                  │
     │  ┌─── 代理工作 ───┐           │
     │  │  第一步           │           │
     │  │  第二步           │           │
     │  │  第三步           │           │
     │  └───────────────────┘           │
     │                                  │
     ▼                                  ▼
[您的提交] ─────────────────► [会话元数据]
     │                           （对话记录、提示、
     │                            修改的文件）
     ▼

检查点会在你工作时保存。当你提交时，会话元数据会被永久存储在 entire/checkpoints/v1 分支上，并与你的提交关联。

策略

Entire 采用手动提交策略，以保持你的 Git 历史整洁：

• 不在你的分支上创建提交 — Entire 绝不会在当前分支上创建任何提交
• 适用于任何分支 — 无论是 main、master 还是特性分支，都能正常使用
• 无破坏性的回退 — 从任意检查点恢复文件，而不会改变提交历史
• 元数据独立存储 — 所有会话数据都保存在 entire/checkpoints/v1 分支上

Git 工作树

Entire 可以与 Git 工作树 无缝协作。每个工作树都有独立的会话跟踪，因此你可以在不同的工作树中同时运行多个 AI 会话，而不会发生冲突。

并发会话

同一份提交上可以同时进行多个 AI 会话。如果你在另一个会话尚未提交时启动第二个会话，Entire 会发出警告，并分别跟踪这两个会话。两个会话的检查点都会被保留，可以独立回退。

本地设备认证测试

如果你正在针对本地的 entire.io 代码库开发 CLI 设备认证流程：

# 在你的应用仓库中
cd ../entire.io-1
mise run dev

# 在本仓库中，将 CLI 指向本地 API
cd ../cli
export ENTIRE_API_BASE_URL=http://localhost:8787

# 运行冒烟测试
./scripts/local-device-auth-smoke.sh

开发过程中的一些实用命令：

# 对本地服务器运行登录流程（会提示按 Enter 键后再打开浏览器）
go run ./cmd/entire login --insecure-http-auth

# 运行登录功能的集成测试覆盖
go test -tags=integration ./cmd/entire/cli/integration_test -run TestLogin

命令参考

命令	描述
entire clean	清理会话数据和孤立的 Entire 数据（使用 --all 可进行仓库范围的清理）
entire disable	从仓库中移除 Entire 钩子
entire doctor	修复或清理卡住的会话
entire enable	在您的仓库中启用 Entire
entire explain	解释一个会话或提交
entire login	使用 Entire 设备认证对 CLI 进行身份验证
entire resume	切换到分支，恢复最新的检查点会话元数据，并显示继续执行的命令
entire rewind	回退到之前的检查点
entire status	显示当前会话信息
entire sessions stop	将一个或多个活动会话标记为结束
entire version	显示 Entire CLI 版本

entire enable 标志

标志	描述
--agent <name>	要为其安装钩子的 AI 助手：claude-code、codex、gemini、opencode、cursor、factoryai-droid 或 copilot-cli
--force, -f	强制重新安装钩子（先移除现有的 Entire 钩子）
--local	将设置写入 settings.local.json 而不是 settings.json
--project	即使 settings.json 已存在，也仍将其写入
--skip-push-sessions	禁用在 Git 推送时自动推送会话日志
--checkpoint-remote <provider:owner/repo>	将检查点分支推送到单独的仓库（例如 github:org/checkpoints-repo）
--telemetry=false	禁用匿名使用情况分析

示例：

# 强制重新安装钩子
entire enable --force

# 将设置保存在本地（不提交到 Git）
entire enable --local

配置

Entire 在 .entire/ 目录中使用两个配置文件：

settings.json（项目设置）

团队共享，通常提交到 Git：

{
  "enabled": true
}

settings.local.json（本地设置）

个人覆盖设置，默认被 Git 忽略：

{
  "enabled": false,
  "log_level": "debug"
}

配置选项

选项	值	描述
enabled	true、false	启用或禁用 Entire
log_level	debug、info、warn、error	日志记录的详细程度
strategy_options.push_sessions	true、false	在 Git 推送时自动推送 entire/checkpoints/v1 分支
strategy_options.checkpoint_remote	{“provider”: “github”, “repo”: “org/repo”}	将检查点分支推送到单独的仓库（见下文）
strategy_options.summarize.enabled	true、false	在提交时自动生成 AI 摘要
telemetry	true、false	向 Posthog 发送匿名使用统计

助手钩子配置

每个助手将其钩子配置存储在其各自的目录中。当您运行 entire enable 时，钩子会安装到所选助手的相应位置：

助手	钩子位置	格式
Claude Code	.claude/settings.json	JSON 钩子配置
Codex	.codex/hooks.json	JSON 钩子配置
Copilot CLI	.github/hooks/entire.json	JSON 钩子配置
Cursor	.cursor/hooks.json	JSON 钩子配置
Factory AI Droid	.factory/settings.json	JSON 钩子配置
Gemini CLI	.gemini/settings.json	JSON 钩子配置
OpenCode	.opencode/plugins/entire.ts	TypeScript 插件

您可以同时启用多个助手——每个助手的钩子都是独立的。Entire 通过检查已安装的钩子来检测哪些助手处于活动状态，而不是通过 settings.json 中的设置。

检查点远程

默认情况下，Entire 会将 entire/checkpoints/v1 推送到与代码相同的远程仓库。如果您希望将检查点数据推送到单独的仓库（例如用于公共项目的私有仓库），可以使用结构化的提供者和仓库配置 checkpoint_remote：

{
  "strategy_options": {
    "checkpoint_remote": {
      "provider": "github",
      "repo": "myorg/checkpoints-private"
    }
  }
}

或者通过 CLI：

entire enable --checkpoint-remote github:myorg/checkpoints-private

Entire 会自动使用与您的推送远程相同的协议（SSH 或 HTTPS）生成 Git URL。它将：

• 如果检查点分支存在于远程但本地不存在，则将其一次性拉取到本地
• 将 entire/checkpoints/v1 推送到检查点仓库，而不是您的默认推送远程
• 如果检测到分叉（推送远程所有者与检查点仓库所有者不同），则跳过推送
• 如果远程无法访问，会发出警告并继续操作，而不会阻止您的主要推送

自动摘要

启用后，Entire 会在提交时为检查点自动生成 AI 摘要。摘要会捕获会话中的意图、结果、经验教训、痛点以及待办事项。

{
  "strategy_options": {
    "summarize": {
      "enabled": true
    }
  }
}

要求：

• 必须安装并认证 Claude CLI（claude 命令需在 PATH 中可用）
• 摘要生成是非阻塞的：如果失败，只会记录日志，不会阻止提交

注意： 目前使用 Claude CLI 生成摘要。未来版本可能会支持其他 AI 后端。

设置优先级

本地设置会逐字段覆盖项目设置。运行 entire status 时，会同时显示项目和本地（生效）设置。

特定于代理的步骤与限制

• 为 Codex 启用 Entire 时，该命令还会创建或更新 .codex/config.toml 文件，并将 codex_hooks = true 设置为启用 Codex 钩子。如果您手动配置 Codex，请确保在 .codex/config.toml 中设置了此标志。或者，在运行 entire enable 时，从交互式代理选择器中选择 Codex。
• Entire 支持 Cursor IDE 和 Cursor Agent CLI 工具，但目前尚不支持 entire rewind 命令。其他命令（如 doctor、status 等）与其他代理的功能相同。
• Entire 支持 Copilot CLI，但不支持 VS Code 中的 Copilot、其他 IDE 或 github.com 上的 Copilot。

安全与隐私

您的会话记录存储在 Git 仓库的 entire/checkpoints/v1 分支中。 如果您的仓库是公开的，这些数据将对任何人可见。

Entire 在写入 entire/checkpoints/v1 时会自动遮盖检测到的敏感信息（API 密钥、令牌、凭据），但遮盖仅为尽力而为。会话期间使用的临时影子分支可能包含未遮盖的数据，不应推送。有关详细信息，请参阅 docs/security-and-privacy.md。

故障排除

常见问题

问题	解决方法
“不是 Git 仓库”	首先导航到一个 Git 仓库
“Entire 已禁用”	运行 entire enable
“未找到回溯点”	使用您配置的代理工作并提交更改
“影子分支冲突”	运行 entire clean --force

SSH 认证错误

如果您在运行 entire resume 时看到如下错误：

无法获取元数据：无法从 origin 获取 entire/checkpoints/v1：ssh：握手失败：ssh：无法认证，尝试的方法 [无, 公钥]，没有剩余的支持方法

这是 go-git 的 SSH 处理已知问题。通过将 GitHub 的主机密钥添加到您的 known_hosts 文件来修复：

ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
ssh-keyscan -t ecdsa github.com >> ~/.ssh/known_hosts

调试模式

# 通过环境变量
ENTIRE_LOG_LEVEL=debug entire status

# 或通过 settings.local.json
{
  "log_level": "debug"
}

清理状态

# 清理当前提交的会话数据
entire clean --force

# 清理整个仓库中的所有孤立数据
entire clean --all --force

# 禁用并重新启用
entire disable && entire enable --force

辅助功能

对于屏幕阅读器用户，可以启用无障碍模式：

export ACCESSIBLE=1
entire enable

这将使用更简单的文本提示，而不是交互式 TUI 元素。

开发

该项目使用 mise 进行任务自动化和依赖管理。

先决条件

• mise - 使用 curl https://mise.run | sh 安装

入门

# 克隆仓库
git clone <repo-url>
cd cli

# 安装依赖项（包括 Go）
mise install

# 信任 mise 配置（首次设置时必需）
mise trust

# 构建 CLI
mise run build

###常用任务

# 运行测试
mise run test

# 运行集成测试
mise run test:integration

# 运行所有测试（单元 + 集成，CI 模式）
mise run test:ci

# 代码 lint 检查
mise run lint

# 格式化代码
mise run fmt

获取帮助

entire --help              # 一般帮助
entire <command> --help    # 命令特定帮助

• GitHub Issues： 在 https://github.com/entireio/cli/issues 报告错误或请求功能
• 贡献： 请参阅 CONTRIBUTING.md 以获取指南

许可证

MIT 许可证 - 详情请参阅 LICENSE。

Entire CLI 快速上手指南

Entire 是一款集成到 Git 工作流中的开源工具，旨在捕获 AI 代理（如 Claude Code、Cursor 等）的会话记录。它将提示词、响应、修改文件等元数据与 Git 提交关联，帮助你理解代码变更原因、随时回滚到之前的检查点，并保持主分支历史整洁。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS、Linux 或 Windows
• 核心依赖：已安装并配置好 Git
• AI 代理：已安装并登录至少一个支持的 AI 编程助手（例如：Claude Code, Cursor, Codex, Gemini, Copilot CLI 等）

安装步骤

根据你的操作系统选择以下任一方式进行安装：

macOS (推荐)

使用 Homebrew 安装：

brew tap entireio/tap
brew install entireio/tap/entire

Windows

使用 Scoop 安装：

scoop bucket add entire https://github.com/entireio/scoop-bucket.git
scoop install entire/cli

Linux / 通用 (Go 环境)

如果你已安装 Go 环境，可以直接编译安装：

go install github.com/entireio/cli/cmd/entire@latest

注意：安装完成后，请确保将 Go 二进制目录添加到环境变量 PATH 中：

export PATH="$HOME/go/bin:$PATH"
# 建议将上述命令添加到 ~/.zshrc 或 ~/.bashrc 以永久生效

基本使用

1. 启用 Entire

进入你的项目根目录，运行以下命令以初始化 Git Hooks 并选择要集成的 AI 代理：

cd your-project && entire enable

系统会提示你选择需要挂钩的 AI 代理。若需非交互式指定代理（例如 Cursor），可使用：entire enable --agent cursor

2. 正常工作

像往常一样使用你的 AI 代理进行编码。Entire 会在后台自动运行：

• 当你或 AI 执行 git commit 时，Entire 会自动创建一个检查点 (Checkpoint)。
• 所有的会话元数据（提示词、回复、文件变动）会被存储在独立的 entire/checkpoints/v1 分支中，不会污染你的主分支历史。

你可以随时查看当前会话状态：

entire status

3. 回滚与恢复

如果 AI 生成的代码不符合预期，你可以轻松回退到之前的任意检查点：

回滚到特定检查点：

entire rewind

该命令会列出所有可用的检查点，选择后即可将代码恢复到该状态。

恢复之前的会话上下文： 如果你想切换到某个分支并恢复最近的会话元数据以便继续工作：

entire resume <branch-name>

4. 停用 (可选)

如果不再需要使用，可以移除 Hooks，这不会影响你的代码和提交历史：

entire disable