Back to Details

entire

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Entire - AI Session Tracking for Git

Entire - Git的AI会话追踪工具

Overview

概述

Entire hooks into your git workflow to capture AI agent sessions on every push. Sessions are indexed alongside commits, creating a searchable record of how code was written in your repo.
Core capabilities:
  • 📸 Checkpoint sessions - Save points you can rewind to
  • ⏪ Rewind to any checkpoint - Restore code to earlier states
  • 📖 Explain sessions - Understand how code was created
  • 🔄 Resume previous work - Pick up where you left off
  • 🩺 Diagnose issues - Fix stuck sessions
Entire 可接入你的Git工作流，在每次推送时捕获AI Agent会话。会话会与提交记录关联索引，为你的代码库创建可搜索的代码编写过程记录。
核心功能：
  • 📸 检查点会话 - 保存可回退的节点
  • ⏪ 回退至任意检查点 - 将代码恢复到早期状态
  • 📖 会话解析 - 了解代码的创建过程
  • 🔄 恢复之前的工作 - 从上次中断处继续
  • 🩺 问题诊断 - 修复停滞的会话

When to Use This Skill

何时使用该工具

Use this skill when:
  • User wants to install/enable Entire
  • User mentions rewinding, undoing, or reverting AI changes
  • User wants to understand how code was generated
  • User asks about session history or checkpoints
  • User encounters Entire errors or stuck sessions
  • User wants to resume previous AI work
Don't use for:
  • Standard git operations (use git directly)
  • Code review (use standard review tools)
  • General debugging (unless related to Entire sessions)
在以下场景使用：
  • 用户想要安装/启用Entire
  • 用户提及回退、撤销或还原AI生成的更改
  • 用户想要了解代码的生成过程
  • 用户询问会话历史或检查点相关内容
  • 用户遇到Entire报错或会话停滞问题
  • 用户想要恢复之前的AI开发工作
请勿用于：
  • 标准Git操作（直接使用Git即可）
  • 代码评审（使用标准评审工具）
  • 常规调试（除非与Entire会话相关）

Prerequisites Check

前置检查

Before helping with Entire, verify:
bash
undefined
在协助用户使用Entire之前，请先验证：
bash
undefined

Check if Entire is installed

检查Entire是否已安装

which entire
which entire

Check if repository has Entire enabled

检查仓库是否已启用Entire

entire status

If not installed, guide user through installation first.
entire status

若未安装，请先引导用户完成安装步骤。

Installation & Setup

安装与配置

Installing Entire

安装Entire

Recommended: Homebrew (macOS/Linux)
bash
brew tap entireio/tap
brew install entireio/tap/entire
Alternative: Go
bash
go install github.com/entireio/cli/cmd/entire@latest
推荐方式：Homebrew（macOS/Linux）
bash
brew tap entireio/tap
brew install entireio/tap/entire
替代方式：Go语言安装
bash
go install github.com/entireio/cli/cmd/entire@latest

Enabling in Repository

在仓库中启用Entire

Default setup (manual-commit strategy):
bash
cd /path/to/your/repo
entire enable
With options:
bash
undefined
默认配置（手动提交策略）：
bash
cd /path/to/your/repo
entire enable
带参数配置：
bash
undefined

Use auto-commit strategy (creates git commits automatically)

使用自动提交策略（自动创建Git提交）

entire enable --strategy auto-commit
entire enable --strategy auto-commit

Setup for Gemini CLI instead of Claude Code

针对Gemini CLI而非Claude Code进行配置

entire enable --agent gemini
entire enable --agent gemini

Disable automatic session push

禁用会话自动推送

entire enable --skip-push-sessions
entire enable --skip-push-sessions

Force reinstall hooks

强制重新安装钩子

entire enable --force
entire enable --force

Save settings locally (not committed to git)

本地保存设置（不提交至Git）

entire enable --local

**What `entire enable` does:**
1. Installs git hooks to track AI sessions
2. Creates `.entire/` directory for configuration
3. Sets up session tracking (default: manual-commit strategy)
4. Your code commits stay clean - session metadata stored separately on `entire/checkpoints/v1` branch

**After enabling:**
```bash
entire status  # Verify Entire is active
entire enable --local

**`entire enable`的作用：**
1. 安装Git钩子以追踪AI会话
2. 创建`.entire/`目录用于存储配置
3. 配置会话追踪（默认：手动提交策略）
4. 代码提交记录保持整洁 - 会话元数据单独存储在`entire/checkpoints/v1`分支

**启用后验证：**
```bash
entire status  # 验证Entire是否激活

Key Concepts

核心概念

Sessions

会话

A session represents a complete interaction with your AI agent from start to finish.
Session ID format: 
YYYY-MM-DD-<UUID>
Example: 
2026-02-11-abc123de-f456-7890-abcd-ef1234567890
Sessions capture:
  • All prompts and responses
  • Files modified
  • Timestamps
  • Agent metadata
Storage: Sessions are stored on the 
entire/checkpoints/v1
branch, separate from your code.
会话代表与AI Agent从开始到结束的完整交互过程。
会话ID格式： 
YYYY-MM-DD-<UUID>
示例：
2026-02-11-abc123de-f456-7890-abcd-ef1234567890
会话会捕获以下内容：
  • 所有提示词与响应
  • 修改的文件
  • 时间戳
  • Agent元数据
存储方式： 会话存储在
entire/checkpoints/v1
分支，与代码分支分离。

Checkpoints

检查点

A checkpoint is a snapshot within a session - a save point you can rewind to.
Checkpoint ID format: 12-character hex string Example: 
a3b2c4d5e6f7
When checkpoints are created:
  • manual-commit strategy (default): When you or agent make a git commit
  • auto-commit strategy: After each agent response
检查点是会话中的一个快照 - 可回退的保存节点。
检查点ID格式： 12位十六进制字符串 示例：
a3b2c4d5e6f7
检查点创建时机：
  • 手动提交策略（默认）：当你或Agent执行Git提交时
  • 自动提交策略：每个Agent响应之后

Strategies

策略对比

StrategyCode CommitsSafe on main?Best For
manual-commit (default)None on your branch✅ YesMost workflows - keeps git history clean
auto-commitAutomatic after each response⚠️ Use cautionTeams wanting automatic code commits
Switching strategies:
bash
entire disable
entire enable --strategy auto-commit
策略代码提交情况主分支安全性适用场景
manual-commit（默认）不会在你的分支创建提交✅ 安全大多数工作流 - 保持Git历史整洁
auto-commit每个响应后自动提交⚠️ 谨慎使用需要自动代码提交的团队
切换策略：
bash
entire disable
entire enable --strategy auto-commit

Core Workflows

核心工作流

1. Check Current Session Status

1. 查看当前会话状态

Always start by checking status:
bash
entire status
Output includes:
  • Current session ID
  • Active strategy
  • Number of checkpoints
  • Whether session is in progress
Interpreting status:
  • "No active session" - Start working with Claude Code/Gemini
  • "Session in progress" - Currently tracking
  • "Entire is disabled" - Run 
    entire enable
始终先检查状态：
bash
entire status
输出包含：
  • 当前会话ID
  • 激活的策略
  • 检查点数量
  • 会话是否正在进行
状态解读：
  • "No active session" - 开始与Claude Code/Gemini交互
  • "Session in progress" - 正在追踪会话
  • "Entire is disabled" - 执行
    entire enable
    启用

2. Rewind to Previous Checkpoint

2. 回退至之前的检查点

When agent makes unwanted changes:
bash
entire rewind
Interactive flow:
  1. Shows list of available checkpoints with:
    • Checkpoint ID
    • Timestamp
    • Associated commit message (if any)
  2. User selects checkpoint
  3. Code restored to that exact state
What rewind does:
  • Restores all files to checkpoint state
  • Preserves session history
  • Non-destructive (can rewind forward again)
Manual-commit strategy:
  • Always allows full rewind
  • Restores files from shadow branch
Auto-commit strategy:
  • Full rewind on feature branches
  • Logs-only on main (preserves shared history)
Example scenario:
User: "The Claude just broke my authentication, I want to go back"
Assistant: Let me help you rewind to before those changes.

$ entire rewind
当Agent产生了不需要的更改时：
bash
entire rewind
交互流程：
  1. 显示可用检查点列表，包含：
    • 检查点ID
    • 时间戳
    • 关联的提交信息（如有）
  2. 用户选择检查点
  3. 代码恢复至该节点的状态
回退操作的作用：
  • 将所有文件恢复到检查点状态
  • 保留会话历史
  • 非破坏性操作（可再次向前回退）
手动提交策略：
  • 始终支持完整回退
  • 从影子分支恢复文件
自动提交策略：
  • 功能分支支持完整回退
  • 主分支仅记录日志（保护共享历史）
示例场景：
用户: "Claude刚搞坏了我的认证系统，我想恢复之前的状态"
助手: 我来帮你回退到这些更改之前的状态。

$ entire rewind

Then guide user through checkpoint selection

然后引导用户选择检查点

undefined
undefined

3. Resume Previous Session

3. 恢复之前的会话

To pick up where you left off on a different branch:
bash
entire resume <branch-name>
What it does:
  1. Checks out the specified branch
  2. Restores latest checkpointed session metadata
  3. Prints command(s) to continue work
Example:
bash
entire resume feature/auth
在不同分支上继续之前的工作：
bash
entire resume <branch-name>
操作作用：
  1. 切换到指定分支
  2. 恢复最近的检查点会话元数据
  3. 打印继续工作的命令
示例：
bash
entire resume feature/auth

Output:

输出:

Checked out branch 'feature/auth'

Checked out branch 'feature/auth'

Restored session: 2026-02-11-abc123de...

Restored session: 2026-02-10-def456gh-i789-0123-jklm-no4567890123

To continue: claude code continue

To continue: claude code continue

undefined
undefined

4. Explain Sessions and Commits

4. 解析会话与提交记录

Understand how code was created:
bash
undefined
了解代码的创建过程：
bash
undefined

Explain current session

解析当前会话

entire explain
entire explain

Explain specific session

解析指定会话

entire explain <session-id>
entire explain <session-id>

Explain specific commit

解析指定提交

entire explain <commit-hash>

**Use cases:**
- "How was this feature implemented?"
- "What prompts led to these changes?"
- "Why did the agent make this decision?"

**Output includes:**
- Session transcript
- Prompts and responses
- Files touched
- Reasoning and context
entire explain <commit-hash>

**适用场景：**
- "这个功能是如何实现的？"
- "哪些提示词导致了这些更改？"
- "Agent为什么做出这个决策？"

**输出包含：**
- 会话记录
- 提示词与响应
- 修改的文件
- 推理过程与上下文

5. Troubleshooting with Doctor

5. 使用Doctor命令排查故障

When sessions are stuck or behaving strangely:
bash
entire doctor
What doctor does:
  • Detects orphaned sessions
  • Identifies conflicting state
  • Suggests fixes
  • Can clean up automatically
Common issues doctor fixes:
  • Stuck sessions that won't checkpoint
  • Shadow branch conflicts
  • Metadata inconsistencies
Example:
User: "Entire says I have a session but I don't see any checkpoints"
Assistant: Let's run the doctor to diagnose this.

$ entire doctor
当会话停滞或出现异常时：
bash
entire doctor
Doctor命令的作用：
  • 检测孤立会话
  • 识别冲突状态
  • 建议修复方案
  • 可自动清理问题
Doctor可修复的常见问题：
  • 无法保存检查点的停滞会话
  • 影子分支冲突
  • 元数据不一致
示例：
用户: "Entire显示我有一个会话，但检查点无法保存"
助手: 让我们用doctor命令来诊断问题。

$ entire doctor

6. Clean Up Orphaned Data

6. 清理孤立数据

Remove unused Entire data:
bash
entire clean
What it cleans:
  • Orphaned shadow branches
  • Old session metadata
  • Unreferenced checkpoints
When to use:
  • After heavy rebasing
  • When switching strategies
  • Periodic maintenance
移除未使用的Entire数据：
bash
entire clean
清理内容：
  • 孤立的影子分支
  • 旧会话元数据
  • 未引用的检查点
使用时机：
  • 大量变基操作后
  • 切换策略时
  • 定期维护

7. Reset Shadow Branch

7. 重置影子分支

Nuclear option when shadow branch is corrupted:
bash
entire reset
⚠️ WARNING: This deletes the shadow branch and session state for current HEAD commit.
When to use:
  • Shadow branch conflicts that doctor can't fix
  • After complex git operations (rebase, merge conflicts)
  • Starting fresh on current commit
What it does:
  • Deletes 
    entire/<HEAD-hash>-<worktree-hash>
    branch
  • Clears session state for current commit
  • Does NOT affect committed checkpoints on 
    entire/checkpoints/v1
Use with force flag:
bash
entire reset --force
当影子分支损坏时的终极解决方案：
bash
entire reset
⚠️ 警告： 此操作会删除当前HEAD提交的影子分支与会话状态。
使用时机：
  • Doctor无法修复的影子分支冲突
  • 复杂Git操作后（变基、合并冲突）
  • 在当前提交上重新开始
操作作用：
  • 删除
    entire/<HEAD-hash>-<worktree-hash>
    分支
  • 清除当前提交的会话状态
  • 不会影响
    entire/checkpoints/v1
    分支上已提交的检查点
带force参数使用：
bash
entire reset --force

8. Disable Entire

8. 禁用Entire

Temporarily or permanently disable:
bash
entire disable
What it does:
  • Removes git hooks
  • Stops session tracking
  • Preserves all existing session data
  • Your code and commit history remain untouched
Re-enable:
bash
entire enable --force
临时或永久禁用：
bash
entire disable
操作作用：
  • 移除Git钩子
  • 停止会话追踪
  • 保留所有现有会话数据
  • 代码与提交历史不受影响
重新启用：
bash
entire enable --force

Configuration

配置说明

Entire uses two config files in 
.entire/
:
Entire在
.entire/
目录下使用两个配置文件：

settings.json (Project Settings)

settings.json（项目设置）

Shared across team, typically committed:
json
{
  "strategy": "manual-commit",
  "agent": "claude-code",
  "enabled": true
}
团队共享，通常会提交至Git：
json
{
  "strategy": "manual-commit",
  "agent": "claude-code",
  "enabled": true
}

settings.local.json (Local Overrides)

settings.local.json（本地覆盖设置）

Personal settings, gitignored:
json
{
  "enabled": false,
  "log_level": "debug"
}
个人设置，会被Git忽略：
json
{
  "enabled": false,
  "log_level": "debug"
}

Key Configuration Options

关键配置选项

OptionValuesDescription
enabled
true
, 
false
Enable/disable Entire
log_level
debug
, 
info
, 
warn
, 
error
Logging verbosity
strategy
manual-commit
, 
auto-commit
Session capture strategy
strategy_options.push_sessions
true
, 
false
Auto-push checkpoints branch
strategy_options.summarize.enabled
true
, 
false
AI-generated summaries
telemetry
true
, 
false
Anonymous usage stats
Editing config:
bash
undefined
选项可选值描述
enabled
true
, 
false
启用/禁用Entire
log_level
debug
, 
info
, 
warn
, 
error
日志详细程度
strategy
manual-commit
, 
auto-commit
会话捕获策略
strategy_options.push_sessions
true
, 
false
自动推送检查点分支
strategy_options.summarize.enabled
true
, 
false
AI生成摘要
telemetry
true
, 
false
匿名使用统计
编辑配置：
bash
undefined

Edit project settings

编辑项目设置

vim .entire/settings.json
vim .entire/settings.json

Edit local settings

编辑本地设置

vim .entire/settings.local.json
vim .entire/settings.local.json

Check effective settings

查看生效的设置

entire status
undefined
entire status
undefined

Advanced Features

高级功能

Auto-Summarization

自动摘要

Generate AI summaries at commit time:
Enable:
json
{
  "strategy_options": {
    "summarize": {
      "enabled": true
    }
  }
}
Requirements:
  • Claude CLI installed and authenticated
  • claude
    command in PATH
What it captures:
  • Intent and outcome
  • Key learnings
  • Friction points
  • Open items
在提交时生成AI摘要：
启用方式：
json
{
  "strategy_options": {
    "summarize": {
      "enabled": true
    }
  }
}
要求：
  • 已安装并认证Claude CLI
  • claude
    命令在PATH中
捕获内容：
  • 意图与结果
  • 关键知识点
  • 卡点
  • 未完成事项

Git Worktrees Support

Git工作区支持

Entire works with git worktrees - each worktree has independent session tracking.
Example:
bash
undefined
Entire支持Git工作区 - 每个工作区有独立的会话追踪。
示例：
bash
undefined

Create worktree

创建工作区

git worktree add ../feature-branch feature/new-auth
git worktree add ../feature-branch feature/new-auth

Enable Entire in worktree

在工作区中启用Entire

cd ../feature-branch entire enable
cd ../feature-branch entire enable

Sessions tracked independently

会话会被独立追踪

undefined
undefined

Concurrent Sessions

并发会话

Multiple sessions can run on same commit:
  • Each tracked separately
  • Independent rewind
  • Entire warns about concurrent work
同一提交上可运行多个会话：
  • 每个会话独立追踪
  • 独立回退
  • Entire会警告并发工作

Troubleshooting Guide

故障排查指南

Common Issues

常见问题

IssueDiagnosisSolution
"Not a git repository"Not in git repoNavigate to git repository
"Entire is disabled"Hooks not installed
entire enable
"No rewind points found"No checkpoints createdMake a commit (manual) or wait for response (auto)
"shadow branch conflict"Corrupted shadow branch
entire reset --force
问题诊断解决方案
"Not a git repository"不在Git仓库中导航到Git仓库目录
"Entire is disabled"钩子未安装
entire enable
"No rewind points found"未创建检查点手动提交或等待Agent响应（自动策略）
"shadow branch conflict"影子分支损坏
entire reset --force

SSH Authentication Errors

SSH认证错误

Error:
ssh: handshake failed: ssh: unable to authenticate
Fix:
bash
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
ssh-keyscan -t ecdsa github.com >> ~/.ssh/known_hosts
This is a known issue with go-git's SSH handling.
错误信息：
ssh: handshake failed: ssh: unable to authenticate
修复方案：
bash
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
ssh-keyscan -t ecdsa github.com >> ~/.ssh/known_hosts
这是go-git的SSH处理已知问题。

Debug Mode

调试模式

Via environment variable:
bash
ENTIRE_LOG_LEVEL=debug entire status
Via settings:
json
{
  "log_level": "debug"
}
Debug logs location: 
.entire/logs/
通过环境变量启用：
bash
ENTIRE_LOG_LEVEL=debug entire status
通过设置启用：
json
{
  "log_level": "debug"
}
调试日志位置： 
.entire/logs/

Stuck Sessions

停滞会话

Symptoms:
  • Checkpoints not saving
  • Status shows old session
  • Rewind points not appearing
Fix:
bash
undefined
症状：
  • 检查点无法保存
  • 状态显示旧会话
  • 回退点不显示
修复方案：
bash
undefined

Try doctor first

先尝试doctor命令

entire doctor
entire doctor

If that fails, reset

如果失败，执行重置

entire reset --force
entire reset --force

Re-enable

重新启用

entire enable --force
undefined
entire enable --force
undefined

Accessibility

无障碍支持

For screen readers:
bash
export ACCESSIBLE=1
entire enable
Uses simpler text prompts instead of interactive TUI.
针对屏幕阅读器用户：
bash
export ACCESSIBLE=1
entire enable
使用更简单的文本提示替代交互式TUI。

Integration with Claude Code

与Claude Code的集成

Entire is designed to work seamlessly with Claude Code:
Entire专为与Claude Code无缝协作设计：

During Development

开发过程中

Claude Code workflow:
  1. User works with Claude Code
  2. Entire automatically tracks session in background
  3. Checkpoints created based on strategy
  4. User can check status anytime: 
    entire status
Typical commands Claude might suggest:
bash
undefined
Claude Code工作流：
  1. 用户与Claude Code交互
  2. Entire在后台自动追踪会话
  3. 根据策略创建检查点
  4. 用户可随时查看状态：
    entire status
Claude可能建议的典型命令：
bash
undefined

Before starting work

开始工作前

entire status
entire status

After significant changes

重大更改后

entire status # Check checkpoint count
entire status # 检查检查点数量

If something goes wrong

出现问题时

entire rewind
entire rewind

When switching tasks

切换任务时

entire resume <branch>
undefined
entire resume <branch>
undefined

When to Suggest Rewind

何时建议使用回退

Proactively suggest rewind when:
  • Agent made changes that broke tests
  • User expresses regret about changes
  • User says "undo", "go back", "revert"
  • Implementation went in wrong direction
Example:
User: "These changes broke the login flow"
Assistant: Let's rewind to before these changes.

$ entire rewind

[Shows checkpoint list - guide user to select pre-breaking checkpoint]
主动建议回退的场景：
  • Agent的更改导致测试失败
  • 用户对更改表示后悔
  • 用户提到"undo"、"go back"、"revert"
  • 实现方向错误
示例：
用户: "这些更改破坏了登录流程"
助手: 让我们回退到这些更改之前的状态。

$ entire rewind

[显示检查点列表 - 引导用户选择故障前的检查点]

When to Suggest Explain

何时建议使用解析

Suggest explain when:
  • User asks "how was this created?"
  • User questions agent's reasoning
  • User debugging mysterious changes
  • User onboarding to codebase
Example:
User: "I don't understand why the auth was implemented this way"
Assistant: Let me show you the session that created this.

$ entire explain src/auth/login.ts

[Shows session transcript and reasoning]
建议使用解析的场景：
  • 用户问"这是如何创建的？"
  • 用户质疑Agent的推理
  • 用户调试不明原因的更改
  • 用户熟悉代码库
示例：
用户: "我不明白为什么认证功能是这样实现的"
助手: 让我展示创建这段代码的会话记录。

$ entire explain src/auth/login.ts

[显示会话记录与推理过程]

Common Scenarios

常见场景示例

Scenario 1: Initial Setup

场景1：初始配置

User: "Set up Entire for me"
Assistant: I'll help you install and enable Entire in this repository.
用户: "帮我设置Entire"
助手: 我来帮你在这个仓库中安装并启用Entire。

First, check if Entire is installed

先检查Entire是否已安装

$ which entire
$ which entire

If not installed

如果未安装

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

Navigate to your repository

导航到你的仓库

$ cd /path/to/your/repo
$ cd /path/to/your/repo

Enable Entire (default: manual-commit strategy)

启用Entire（默认手动提交策略）

$ entire enable
$ entire enable

Verify it's working

验证是否正常工作

$ entire status
Entire is now tracking your AI sessions! Work normally with Claude Code, and checkpoints will be created when you commit.
undefined
$ entire status
Entire现在会追踪你的AI会话！正常使用Claude Code即可，提交时会自动创建检查点。
undefined

Scenario 2: Undo Unwanted Changes

场景2：撤销不需要的更改

User: "Claude just broke my authentication system, I need to undo this"
Assistant: Let's rewind to before those changes.

$ entire rewind

[Interactive checkpoint list appears]
Available checkpoints:
1. a3b2c4d5e6f7 - 2026-02-11 14:23 - "Add login validation"
2. f9e8d7c6b5a4 - 2026-02-11 14:15 - "Initial auth setup"
3. 1a2b3c4d5e6f - 2026-02-11 14:00 - "Create user model"

Select checkpoint to rewind to: 2

[Code restored to checkpoint 2]

Your code has been restored to the state before the breaking changes.
You can now continue working from this checkpoint.
用户: "Claude刚搞坏了我的认证系统，我需要撤销这些更改"
助手: 让我们回退到这些更改之前的状态。

$ entire rewind

[显示检查点列表]
可用检查点:
1. a3b2c4d5e6f7 - 2026-02-11 14:23 - "添加登录验证"
2. f9e8d7c6b5a4 - 2026-02-11 14:15 - "初始认证设置"
3. 1a2b3c4d5e6f - 2026-02-11 14:00 - "创建用户模型"

选择要回退的检查点: 2

[代码恢复到检查点2的状态]

你的代码已恢复到故障前的状态，现在可以从该检查点继续工作。

Scenario 3: Understanding Generated Code

场景3：了解代码生成过程

User: "How was this payment processing code created?"
Assistant: Let me show you the session that generated this code.

$ entire explain src/payment/processor.ts

Session: 2026-02-11-abc123de-f456-7890-abcd-ef1234567890
Date: 2026-02-11 13:45 - 14:30

Prompts & Responses:
1. User: "Add Stripe payment processing"
   Claude: [Implemented payment processor with retry logic...]

2. User: "Add error handling for failed payments"
   Claude: [Added try-catch blocks and error logging...]

3. User: "Add webhook handling"
   Claude: [Created webhook endpoint and validation...]

Files Modified:
- src/payment/processor.ts (created)
- src/payment/webhooks.ts (created)
- src/api/routes.ts (modified)

This shows you the full context of how the payment system was built.
用户: "这段支付处理代码是如何创建的？"
助手: 让我展示生成这段代码的会话记录。

$ entire explain src/payment/processor.ts

会话: 2026-02-11-abc123de-f456-7890-abcd-ef1234567890
时间: 2026-02-11 13:45 - 14:30

提示词与响应:
1. 用户: "添加Stripe支付处理"
   Claude: [实现了带重试逻辑的支付处理器...]

2. 用户: "为支付失败添加错误处理"
   Claude: [添加了try-catch块与错误日志...]

3. 用户: "添加Webhook处理"
   Claude: [创建了Webhook端点与验证逻辑...]

修改的文件:
- src/payment/processor.ts（新建）
- src/payment/webhooks.ts（新建）
- src/api/routes.ts（修改）

这展示了支付系统构建的完整上下文。

Scenario 4: Resume Previous Work

场景4：恢复之前的工作

User: "I want to continue working on the feature/auth branch"
Assistant: Let me help you resume that work.

$ entire resume feature/auth

Checked out branch 'feature/auth'
Restored session: 2026-02-10-def456gh-i789-0123-jklm-no4567890123
Last checkpoint: b1a2c3d4e5f6 - "Add password reset flow"

To continue:
$ claude code continue

You can now pick up where you left off on the auth feature.
用户: "我想继续在feature/auth分支上工作"
助手: 我来帮你恢复该分支的工作会话。

$ entire resume feature/auth

已切换到分支'feature/auth'
已恢复会话: 2026-02-10-def456gh-i789-0123-jklm-no4567890123
最后一个检查点: b1a2c3d4e5f6 - "添加密码重置流程"

继续工作请执行:
$ claude code continue

你现在可以在认证功能分支上从中断处继续工作。

Scenario 5: Debugging Stuck Session

场景5：调试停滞会话

User: "Entire says I have a session but checkpoints aren't saving"
Assistant: Let's diagnose this with the doctor command.

$ entire doctor

Diagnosing Entire state...

Issues found:
✗ Orphaned session state detected
✗ Shadow branch missing for current HEAD
✓ Configuration valid
✓ Git hooks installed

Suggested fixes:
1. Clean orphaned session: entire clean
2. Reset shadow branch: entire reset --force

Run these fixes? [y/n]: y

Cleaning orphaned data...
Resetting shadow branch...

✓ Fixed! Run 'entire enable --force' to restart session tracking.

$ entire enable --force

Your Entire installation is now healthy and ready to track sessions.
用户: "Entire显示我有一个会话，但检查点无法保存"
助手: 让我们用doctor命令来诊断问题。

$ entire doctor

正在诊断Entire状态...

发现问题:
✗ 检测到孤立会话状态
✗ 当前HEAD的影子分支缺失
✓ 配置有效
✓ Git钩子已安装

建议修复方案:
1. 清理孤立会话: entire clean
2. 重置影子分支: entire reset --force

是否执行修复? [y/n]: y

正在清理孤立数据...
正在重置影子分支...

✓ 修复完成! 执行'entire enable --force'重新开始会话追踪。

$ entire enable --force

你的Entire现在已恢复正常，可以开始追踪会话了。

Scenario 6: Switching Strategies

场景6：切换策略

User: "I want Entire to automatically commit after each response"
Assistant: I'll switch you to the auto-commit strategy.
用户: "我想让Entire在每个响应后自动提交"
助手: 我来帮你切换到自动提交策略。

First, disable current setup

先禁用当前配置

$ entire disable
$ entire disable

Re-enable with auto-commit strategy

启用自动提交策略

$ entire enable --strategy auto-commit
$ entire enable --strategy auto-commit

Verify new strategy

验证新策略

$ entire status
Strategy: auto-commit Checkpoints will now be created automatically after each agent response, with code committed to your active branch.
Note: Be cautious using auto-commit on main/master branches.
undefined
$ entire status
策略: auto-commit 现在会在每个Agent响应后自动创建检查点，并将代码提交到你的当前分支。
注意: 在main/master分支上使用自动提交请谨慎。
undefined

Scenario 7: Exploring Session History

场景7：浏览会话历史

User: "Show me all the sessions where we worked on authentication"
Assistant: Let me search through your Entire session history.

$ entire explain --help  # Check available options
用户: "展示所有与认证相关的会话"
助手: 让我搜索你的Entire会话历史。

$ entire explain --help  # 查看可用选项

List recent sessions

列出最近的会话

$ git log entire/checkpoints/v1 --oneline | grep -i auth
$ git log entire/checkpoints/v1 --oneline | grep -i auth

Explain specific session

解析指定会话

$ entire explain 2026-02-09-auth-session-id
This will show all sessions related to authentication work. You can then use 'entire explain' on specific sessions to see details.
undefined
$ entire explain 2026-02-09-auth-session-id
这会展示所有与认证工作相关的会话，你可以使用'entire explain'查看具体会话的详情。
undefined

Best Practices

最佳实践

When to Proactively Suggest Entire

何时主动推荐Entire

As Claude, suggest Entire when:
  1. Before risky changes:
    "I'm about to refactor the database layer. Let's checkpoint first."
$ entire status  # Verify session tracking
  2. After breaking changes:
    "The tests are failing after my changes. Let's rewind."
$ entire rewind
  3. When user is confused:
    "You seem unsure about these changes. We can always rewind if needed."
$ entire status  # Show current checkpoint count
  4. During complex iterations:
    "We're on iteration 3 of this feature. Previous checkpoints are available if we need to backtrack."
作为Claude，在以下场景推荐Entire：
  1. 风险更改前：
    "我即将重构数据库层，先创建一个检查点。"
$ entire status  # 验证会话追踪状态
  2. 出现故障后：
    "测试在我的更改后失败了，让我们回退。"
$ entire rewind
  3. 用户困惑时：
    "你似乎对这些更改有疑问，我们随时可以回退。"
$ entire status  # 显示当前检查点数量
  4. 复杂迭代中：
    "我们正在进行该功能的第3次迭代，如果需要可以回退到之前的检查点。"

Communication Patterns

沟通规范

Clear checkpoint messaging:
✓ "Checkpoint saved. You can rewind to this point anytime."
✓ "This is checkpoint 3 in this session. Previous states are preserved."
✓ "I've committed the changes. Entire created a checkpoint automatically."

✗ Don't say: "Changes saved" (ambiguous)
✗ Don't say: "Committed" (unclear if checkpoint was created)
Rewind guidance:
✓ "Let's rewind to before these changes using 'entire rewind'"
✓ "We have 5 checkpoints - which point would you like to restore?"
✓ "Rewind is non-destructive - we can always move forward again"

✗ Don't say: "Let's undo this" (unclear if using git or Entire)
✗ Don't say: "Revert to previous version" (ambiguous)
清晰的检查点告知：
✓ "已保存检查点，你可随时回退至此节点。"
✓ "这是本次会话的第3个检查点，之前的状态已保留。"
✓ "我已提交更改，Entire自动创建了检查点。"

✗ 避免说: "更改已保存"（表述模糊）
✗ 避免说: "已提交"（未明确是否创建检查点）
回退引导：
✓ "让我们使用'entire rewind'回退到这些更改之前的状态"
✓ "我们有5个检查点 - 你想恢复到哪个节点？"
✓ "回退是无损操作 - 我们之后还可以再次向前恢复"

✗ 避免说: "让我们撤销这个"（未明确使用Git还是Entire）
✗ 避免说: "恢复到之前的版本"（表述模糊）

Integration with Development Workflow

与开发工作流的集成

Start of session:
bash
entire status  # Check what's being tracked
During development:
  • Work naturally with Claude Code
  • Checkpoints happen automatically (based on strategy)
  • Check status occasionally: 
    entire status
When things go wrong:
bash
entire rewind  # Interactive restore
Switching branches:
bash
entire resume <branch>  # Restore session context
End of day:
bash
entire status  # See final checkpoint count
git push  # Pushes code + checkpoints (if configured)
会话开始时：
bash
entire status  # 检查当前追踪状态
开发过程中：
  • 正常与Claude Code交互
  • 检查点会自动创建（基于策略）
  • 偶尔检查状态: 
    entire status
出现问题时：
bash
entire rewind  # 交互式恢复
切换分支时：
bash
entire resume <branch>  # 恢复会话上下文
每日结束时：
bash
entire status  # 查看最终检查点数量
git push  # 推送代码与检查点（若已配置）

Privacy & Security

隐私与安全

What Entire captures:
  • Session transcripts (prompts & responses)
  • File paths and modifications
  • Timestamps and metadata
  • Agent configuration
What Entire doesn't capture:
  • Credentials or secrets
  • Files outside repository
  • User's system information
Logs location: 
.entire/logs/
(gitignored by default)
Session metadata: Stored on 
entire/checkpoints/v1
branch
Entire会捕获的内容：
  • 会话记录（提示词与响应）
  • 文件路径与修改内容
  • 时间戳与元数据
  • Agent配置
Entire不会捕获的内容：
  • 凭据或密钥
  • 仓库外的文件
  • 用户的系统信息
日志位置： 
.entire/logs/
（默认被Git忽略）
会话元数据： 存储在
entire/checkpoints/v1
分支

Team Usage

团队使用

Sharing checkpoints:
  • Configure 
    strategy_options.push_sessions: true
  • Team members can see session history
  • Useful for:
    • Understanding how code was built
    • Onboarding new developers
    • Code archaeology
    • Learning from AI sessions
Personal usage:
  • Keep 
    push_sessions: false
    for private sessions
  • Use 
    .entire/settings.local.json
    for personal preferences
共享检查点：
  • 配置
    strategy_options.push_sessions: true
  • 团队成员可查看会话历史
  • 适用于：
    • 了解代码的构建过程
    • 新开发者入职
    • 代码溯源
    • 从AI会话中学习
个人使用：
  • 保持
    push_sessions: false
    以保留私有会话
  • 使用
    .entire/settings.local.json
    配置个人偏好

Command Reference Quick Guide

命令速查指南

CommandUse WhenOutput
entire status
Check current sessionSession info, strategy, checkpoint count
entire enable
First time setupInstalls hooks, creates config
entire rewind
Undo changesInteractive checkpoint selection
entire resume <branch>
Switch branches with contextRestores session, prints continue command
entire explain
Understand code creationSession transcript and metadata
entire doctor
Fix issuesDiagnoses and suggests fixes
entire clean
Remove orphaned dataCleans up unused branches/metadata
entire reset
Nuclear optionDeletes shadow branch for current HEAD
entire disable
Stop trackingRemoves hooks, preserves data
entire version
Check CLI versionVersion number
命令使用场景输出
entire status
查看当前会话会话信息、策略、检查点数量
entire enable
首次配置安装钩子、创建配置
entire rewind
撤销更改交互式检查点选择
entire resume <branch>
带上下文切换分支恢复会话、打印继续命令
entire explain
了解代码创建过程会话记录与元数据
entire doctor
修复问题诊断并建议修复方案
entire clean
移除孤立数据清理未使用的分支/元数据
entire reset
终极解决方案删除当前HEAD的影子分支
entire disable
停止追踪移除钩子、保留数据
entire version
查看CLI版本版本号

Error Messages & Solutions

错误信息与解决方案

"Not a git repository"

"Not a git repository"

Cause: Running Entire outside a git repository Solution: 
cd
into your git repository first
原因： 在Git仓库外运行Entire 解决方案： 
cd
到Git仓库目录

"Entire is disabled"

"Entire is disabled"

Cause: Hooks not installed Solution: 
entire enable
原因： 钩子未安装 解决方案： 
entire enable

"No rewind points found"

"No rewind points found"

Cause: No checkpoints created yet Solution:
  • manual-commit: Make a git commit
  • auto-commit: Wait for next agent response
  • Check strategy: 
    entire status
原因： 未创建检查点 解决方案：
  • 手动提交策略： 执行Git提交
  • 自动提交策略： 等待Agent响应
  • 检查策略: 
    entire status

"shadow branch conflict"

"shadow branch conflict"

Cause: Corrupted shadow branch state Solution: 
entire reset --force
原因： 影子分支状态损坏 解决方案： 
entire reset --force

"Failed to fetch metadata: ssh: handshake failed"

"Failed to fetch metadata: ssh: handshake failed"

Cause: go-git SSH bug Solution:
bash
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
ssh-keyscan -t ecdsa github.com >> ~/.ssh/known_hosts
原因： go-git的SSH bug 解决方案：
bash
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
ssh-keyscan -t ecdsa github.com >> ~/.ssh/known_hosts

"Session in unexpected state"

"Session in unexpected state"

Cause: Interrupted operations or git conflicts Solution:
bash
entire doctor  # Try automatic fix first
entire reset --force  # If doctor can't fix
entire enable --force  # Restart tracking
原因： 操作中断或Git冲突 解决方案：
bash
entire doctor  # 先尝试自动修复
entire reset --force  # 如果Doctor无法修复
entire enable --force  # 重新开始追踪

Advanced Usage

高级用法

Custom Configuration

自定义配置

Project-wide settings (
.entire/settings.json
):
json
{
  "strategy": "manual-commit",
  "agent": "claude-code",
  "enabled": true,
  "strategy_options": {
    "push_sessions": true,
    "summarize": {
      "enabled": true
    }
  },
  "telemetry": false
}
Personal overrides (
.entire/settings.local.json
):
json
{
  "log_level": "debug",
  "strategy_options": {
    "push_sessions": false
  }
}
项目全局设置（
.entire/settings.json
）：
json
{
  "strategy": "manual-commit",
  "agent": "claude-code",
  "enabled": true,
  "strategy_options": {
    "push_sessions": true,
    "summarize": {
      "enabled": true
    }
  },
  "telemetry": false
}
个人覆盖设置（
.entire/settings.local.json
）：
json
{
  "log_level": "debug",
  "strategy_options": {
    "push_sessions": false
  }
}

Multiple Agents

多Agent支持

Enable both Claude Code and Gemini CLI:
bash
undefined
同时启用Claude Code与Gemini CLI：
bash
undefined

Enable Claude Code (default)

启用Claude Code（默认）

entire enable --agent claude-code
entire enable --agent claude-code

Also enable Gemini

同时启用Gemini

entire enable --agent gemini
entire enable --agent gemini

Both agents can be tracked simultaneously

两个Agent可同时被追踪

undefined
undefined

Session Metadata Structure

会话元数据结构

Session ID: 
YYYY-MM-DD-<UUID>
Checkpoint ID: 12-char hex string
Metadata location:
  • Active sessions: 
    .git/entire-sessions/
  • Committed checkpoints: 
    entire/checkpoints/v1
    branch
Session files include:
  • transcript.jsonl
    - Full conversation
  • metadata.json
    - Session info
  • files.json
    - Modified files list
会话ID： 
YYYY-MM-DD-<UUID>
检查点ID： 12位十六进制字符串
元数据位置：
  • 活跃会话: 
    .git/entire-sessions/
  • 已提交的检查点: 
    entire/checkpoints/v1
    分支
会话文件包含：
  • transcript.jsonl
    - 完整对话记录
  • metadata.json
    - 会话信息
  • files.json
    - 修改文件列表

Git Worktree Isolation

Git工作区隔离

Each worktree gets independent session tracking:
bash
undefined
每个工作区有独立的会话追踪：
bash
undefined

Main worktree

主工作区

cd /repo entire enable
cd /repo entire enable

Sessions: .git/entire-sessions/main/

会话存储: .git/entire-sessions/main/

Feature worktree

功能工作区

git worktree add ../feature feature/new-ui cd ../feature entire enable
git worktree add ../feature feature/new-ui cd ../feature entire enable

Sessions: .git/entire-sessions/feature-worktree-hash/

会话存储: .git/entire-sessions/feature-worktree-hash/

undefined
undefined

Limitations & Known Issues

限制与已知问题

Known Limitations

已知限制

  1. SSH Authentication - go-git v5 SSH bug requires manual known_hosts setup
  2. Large Repositories - Very large sessions may be slow to explain
  3. Concurrent Sessions - Warning shown, but both tracked independently
  4. Windows Support - Requires WSL (Windows Subsystem for Linux)
  1. SSH认证 - go-git v5的SSH bug需要手动配置known_hosts
  2. 大型仓库 - 非常大的会话在解析时可能较慢
  3. 并发会话 - 会显示警告，但仍会独立追踪
  4. Windows支持 - 需要WSL（Windows Subsystem for Linux）

Gemini CLI Support

Gemini CLI支持

Currently in preview:
目前处于预览阶段：

Auto-Summarization

自动摘要

Requirements:
  • Claude CLI must be installed
  • claude
    command in PATH
  • Authenticated with Claude
If summarization fails:
  • Non-blocking - commit still succeeds
  • Check 
    .entire/logs/
    for errors
要求：
  • 已安装Claude CLI
  • claude
    命令在PATH中
  • 已认证Claude
如果摘要生成失败：
  • 不会阻塞提交
  • 查看
    .entire/logs/
    中的错误日志

Getting Help

获取帮助

Resources

资源

Command Help

命令帮助

bash
entire --help              # General help
entire <command> --help    # Command-specific help
entire status --help       # Example: status help
bash
entire --help              # 通用帮助
entire <command> --help    # 命令专属帮助
entire status --help       # 示例：查看status命令帮助

When Helping Users

协助用户时的注意事项

Before suggesting Entire commands:
  1. Check if Entire is installed: 
    which entire
  2. Check if enabled: 
    entire status
  3. Verify git repository: Inside git repo?
Guide users step by step:
  1. Install (if needed)
  2. Enable (if not enabled)
  3. Explain what will happen
  4. Run the command
  5. Interpret the output
Be specific about outcomes:
  • What checkpoint will be restored
  • What files will change
  • Whether operation is reversible
在推荐Entire命令之前：
  1. 检查Entire是否已安装: 
    which entire
  2. 检查是否已启用: 
    entire status
  3. 验证是否在Git仓库中
逐步引导用户：
  1. 安装（若未安装）
  2. 启用（若未启用）
  3. 解释操作会产生的结果
  4. 执行命令
  5. 解读输出
明确说明操作结果：
  • 会恢复哪个检查点
  • 哪些文件会被更改
  • 操作是否可逆

Summary

总结

Entire is a git workflow enhancement for AI-assisted development that:
✅ Captures AI sessions as checkpoints ✅ Preserves full session history and reasoning ✅ Enables rewinding to any checkpoint ✅ Explains how code was created ✅ Resumes previous work contexts ✅ Diagnoses and fixes session issues
Key principles:
  • Non-invasive (separate metadata storage)
  • Reversible (rewind is non-destructive)
  • Team-friendly (shareable session history)
  • Privacy-conscious (configurable data sharing)
When in doubt:
  • Run 
    entire status
    to see current state
  • Use 
    entire doctor
    to diagnose issues
  • Rewind is always safe - you can rewind forward again
Entire是一款用于AI辅助开发的Git工作流增强工具，它可以：
✅ 捕获 AI会话作为检查点 ✅ 保留完整的会话历史与推理过程 ✅ 支持回退至任意检查点 ✅ 解析代码的创建过程 ✅ 恢复之前的工作上下文 ✅ 诊断并修复会话问题
核心原则：
  • 非侵入式（元数据与代码分离存储）
  • 可逆（回退操作无损）
  • 团队友好（可共享会话历史）
  • 注重隐私（可配置数据共享）
遇到疑问时：
  • 执行
    entire status
    查看当前状态
  • 使用
    entire doctor
    诊断问题
  • 回退操作始终安全 - 你可以再次向前恢复

Skill Activation Note

工具激活说明

This skill is activated when:
  • User mentions Entire, checkpoints, or rewinding
  • User wants to undo AI changes
  • User asks about session history
  • User encounters Entire errors
  • Setup/installation is needed
Always verify Entire is installed and enabled before suggesting commands.
当出现以下情况时，该工具会被激活：
  • 用户提及Entire、检查点或回退
  • 用户想要撤销AI生成的更改
  • 用户询问会话历史
  • 用户遇到Entire报错
  • 需要进行安装/配置
在推荐命令之前，请始终验证Entire是否已安装并启用。