session-crosslink

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Session Crosslink

会话交叉关联

Response Format

响应格式

Begin the first response to this skill invocation with the line:

Entire Session Crosslink:

followed by a blank line, then the content. Apply the header to the first response of the invocation only — not on follow-up turns and not on error / early-exit responses (no session resolved, no affected repos found).

首次响应该技能调用时，需以以下行开头：

Entire Session Crosslink:

随后空一行，再添加内容。仅在首次调用响应中添加该头部——后续对话轮次、错误/提前退出响应（未解析到会话、未找到受影响仓库）无需添加。

STOP — Read these rules before doing ANYTHING

停止操作——执行任何操作前请阅读以下规则

Do NOT ask clarifying questions until the resolver/discovery steps have run. The session id and candidate repo list usually resolve from
```
entire session current --json
```
plus what the user said. Only ask if both come back empty.
Do NOT run
entire session attach
without showing the preview table first. The whole point of this skill is preview-then-confirm.
```
attach
```
amends the target repo's HEAD; previewing wrong means amending the wrong commit.
Always
cd
into the target repo before running
entire session attach
. The CLI resolves the repo from cwd. Use one
```
cd … && entire session attach …
```
per call so each invocation hits the right repo.

Required CLI:

entire

0.6.2+. No special flags needed — this skill works against the shipped CLI via cwd-scoped

entire session attach

在完成解析/发现步骤前，请勿询问澄清问题。会话ID和候选仓库列表通常可通过
```
entire session current --json
```
命令结合用户描述解析得到。仅当两者均返回空值时才需询问。
在展示预览表格前，请勿执行
entire session attach
命令。本技能的核心是先预览再确认。
```
attach
```
命令会修改目标仓库的HEAD提交；若预览错误，将导致修改错误的提交。
执行
entire session attach
前，请务必切换到目标仓库目录（cd）。CLI工具会根据当前工作目录（cwd）解析仓库。每次调用使用一条
```
cd … && entire session attach …
```
命令，确保每次调用都指向正确的仓库。

所需CLI工具：

entire

0.6.2及以上版本。无需特殊参数——本技能通过基于cwd范围的

entire session attach

命令与官方CLI工具配合工作。

Flow

流程

Step 1: Resolve the session id

步骤1：解析会话ID（session id）

Try each strategy in order until one returns a session id.

Strategy A: Entire-enabled cwd.

bash

entire session current --json

If the output is valid JSON and has a non-empty

session_id

, read

session_id

and

agent

and continue with those values. If the JSON parses but

session_id

is missing or empty, treat Strategy A as failed and fall through to B — don't proceed to attach with no session id.

Strategy B: Entire-enabled sibling repo. If the user named a repo that has Entire enabled (e.g.

the foo repo

cd

there and re-try

entire session current --json

. The session state lives wherever the session was tracked.

Strategy C: Runtime-specific transcript directory. If neither A nor B works, the session was never recorded by Entire and you must read it from the agent runtime:

Claude Code: transcripts live at
```
~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
```
. Encoded cwd is the launch directory with
```
/
```
→
```
-
```
. The most recent
```
.jsonl
```
file under the project directory matching the agent's launch cwd is this session. Read the basename minus
```
.jsonl
```
as
```
session_id
```
. Set
```
agent
```
to
```
claude-code
```
.

Codex: check

$CODEX_HOME/sessions/

~/.codex/sessions/

. Set

agent

codex

Other runtimes: ask the user for the session id.

Record

agent

so Step 4 can pass

--agent <name>

to attach.

If all strategies fail: print "Could not resolve a session id — pass one explicitly or run from an Entire-enabled directory" and stop.

按顺序尝试以下策略，直到获取到会话ID。

策略A：已启用Entire的当前工作目录（cwd）

bash

entire session current --json

若输出为有效的JSON且包含非空的

session_id

字段，则读取

session_id

和

agent

的值并继续。若JSON解析成功但

session_id

缺失或为空，则判定策略A失败，转而尝试策略B——切勿在无会话ID的情况下继续执行关联操作。

策略B：已启用Entire的同级仓库。若用户指定了已启用Entire的仓库（例如"foo仓库"），则切换到该仓库目录并重新执行

entire session current --json

命令。会话状态存储在会话被追踪的位置。

策略C：特定运行时的转录文件目录。若策略A和B均失败，说明会话未被Entire追踪，需从Agent运行时读取：

Claude Code：转录文件存储在
```
~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
```
。Encoded cwd是将启动目录中的
```
/
```
替换为
```
-
```
后的路径。项目目录下与Agent启动目录匹配的最新
```
.jsonl
```
文件即为当前会话。读取文件名（去除
```
.jsonl
```
后缀）作为
```
session_id
```
，并将
```
agent
```
设为
```
claude-code
```
。

Codex：检查

$CODEX_HOME/sessions/

或

~/.codex/sessions/

目录。将

agent

设为

codex

。

其他运行时：询问用户提供会话ID。

记录

agent

的值，以便步骤4执行

attach

命令时传递

--agent <name>

参数。

若所有策略均失败：输出"无法解析会话ID——请显式提供会话ID或从已启用Entire的目录运行命令"并停止操作。

Step 2: Discover affected repos

步骤2：发现受影响的仓库

Build a candidate set, union from these sources, then de-duplicate by path:

From the user's message: any repo paths or aliases the user named explicitly (e.g. "the foo repo and the bar api"). Resolve aliases via the user's
```
CLAUDE.md
```
or treat as filesystem paths.
From sibling repos under the launch directory (only if launch dir is NOT Entire-enabled): list immediate subdirectories that have their own
```
.git
```
and a
```
.entire/settings.json
```
.
From the agent's edit history in this session: any repo whose files were edited during the session — derive from the agent's own context. If unsure, ask the user.

For each candidate, run

entire status --json

(with cwd inside that repo) and decide:

```
"enabled": true
```
→ keep.
```
"enabled": false
```
with a settings-parse error (
```
unknown field "..."
```
) → keep. Status fails noisily on misconfigured local settings even when attach would succeed.
```
"enabled": false
```
with no error → drop. Repo opted out of Entire.

If the candidate set is empty, ask the user which repos to crosslink.

构建候选仓库集合，合并以下来源的结果，然后按路径去重：

用户消息：用户明确提及的任何仓库路径或别名（例如"foo仓库和bar api仓库"）。通过用户的
```
CLAUDE.md
```
解析别名，或直接视为文件系统路径。
启动目录下的同级仓库（仅当启动目录未启用Entire时）：列出所有包含独立
```
.git
```
目录和
```
.entire/settings.json
```
文件的直接子目录。
本次会话中Agent的编辑历史：会话期间被编辑文件所属的仓库——从Agent自身的上下文推导。若不确定，询问用户。

对每个候选仓库，切换到该仓库目录并执行

entire status --json

命令，然后根据结果决定：

```
"enabled": true
```
→ 保留该仓库。
```
"enabled": false
```
且存在配置解析错误（如
```
unknown field "..."
```
）→ 保留该仓库。即使关联操作可成功执行，状态检查仍会因本地配置错误而失败。
```
"enabled": false
```
且无错误→ 排除该仓库。该仓库已选择退出Entire。

若候选仓库集合为空，询问用户需要交叉关联哪些仓库。

Step 3: Compute the preview locally

步骤3：本地计算预览结果

For each candidate, inspect git and the session store to compute the action — same logic

entire session attach

uses internally, but without amending anything:

bash

undefined

对每个候选仓库，检查git和会话存储以计算操作——与

entire session attach

命令内部逻辑相同，但不会修改任何内容：

bash

undefined

Get HEAD hash and message

获取HEAD哈希值和提交信息

HEAD_HASH=$(git -C <repo> rev-parse HEAD) HEAD_MSG=$(git -C <repo> log -1 --format=%B HEAD)

Existing Entire-Checkpoint trailer on HEAD, if any

HEAD提交中已存在的Entire-Checkpoint trailer（若有）

EXISTING_TRAILER=$(printf '%s\n' "$HEAD_MSG" | grep -E '^Entire-Checkpoint:' | tail -1 | awk '{print $2}')

Is the session already tracked in this repo's store?

该仓库的存储中是否已追踪该会话？

STATE_FILE=<repo>/.git/entire-sessions/<session-id>.json


Decide the action per repo:

- Both `STATE_FILE` exists AND its `last_checkpoint_id` field is non-empty → `would_skip_existing_in_state`. Attach is a no-op; report that.
- HEAD has an `EXISTING_TRAILER` → `would_link_existing_in_head`. Attach reuses that checkpoint id and adds this session to it.
- Neither → `would_add_trailer`. Attach generates a fresh checkpoint id and amends HEAD with it.

For `would_link_existing_in_head` rows, the checkpoint id is `EXISTING_TRAILER`. For `would_add_trailer` rows, the checkpoint id can't be known ahead of time — attach generates one at write time. Show "new" in the table.

If HEAD has no commits in the repo (`git rev-parse` fails), record an error row: `error: no commits yet`.

STATE_FILE=<repo>/.git/entire-sessions/<session-id>.json


为每个仓库决定操作：

- `STATE_FILE`存在且其`last_checkpoint_id`字段非空 → `would_skip_existing_in_state`。关联操作无实际效果；需告知用户。
- HEAD提交包含`EXISTING_TRAILER` → `would_link_existing_in_head`。关联操作将复用该检查点ID并将会话添加到其中。
- 两者都不满足 → `would_add_trailer`。关联操作将生成新的检查点ID并修改HEAD提交添加该检查点。

对于`would_link_existing_in_head`的行，检查点ID为`EXISTING_TRAILER`。对于`would_add_trailer`的行，检查点ID无法提前获知——关联操作会在写入时生成。在表格中显示"new"。

若仓库中HEAD无提交（`git rev-parse`命令失败），记录错误行：`error: no commits yet`。

Step 4: Render the preview table

步骤4：渲染预览表格

Show the user a compact table:

repo                              HEAD commit   action                          checkpoint
foo                               a1b2c3d       would_add_trailer               (new)
bar                               e4f5g6h       would_link_existing_in_head     ckpt-7d6c
baz                               —             error: no commits yet           —

Then ask: "Attach session

<id>

to the would_* rows? Error rows and

would_skip_existing_in_state

rows will be skipped."

向用户展示简洁表格：

repo                              HEAD commit   action                          checkpoint
foo                               a1b2c3d       would_add_trailer               (new)
bar                               e4f5g6h       would_link_existing_in_head     ckpt-7d6c
baz                               —             error: no commits yet           —

然后询问："是否将会话

<id>

关联到标记为would_*的行？错误行和

would_skip_existing_in_state

行将被跳过。"

Step 5: Execute on confirmation

步骤5：确认后执行操作

For each row the user confirmed where

action

would_add_trailer

would_link_existing_in_head

bash

cd <repo> && entire session attach <session-id> --agent <agent> --force

Skip

would_skip_existing_in_state

rows (re-attach there is a no-op) and

error:

rows.

Capture exit status per repo. Report a final summary:

attached:
  foo    ckpt-9f8e  (new trailer on a1b2c3d)
  bar    ckpt-7d6c  (added to existing checkpoint on e4f5g6h)
skipped:
  baz    (no commits yet)
  qux    (already linked: ckpt-c97b)

Remind the user: attach amends HEAD, so each touched repo's local branch has diverged from its remote. If those branches have open PRs, force-push (

git push --force-with-lease

) to update them.

对用户确认的、

action

为

would_add_trailer

或

would_link_existing_in_head

的每一行：

bash

cd <repo> && entire session attach <session-id> --agent <agent> --force

跳过

would_skip_existing_in_state

行（重新关联无实际效果）和错误行。

捕获每个仓库的退出状态。输出最终总结：

attached:
  foo    ckpt-9f8e  (new trailer on a1b2c3d)
  bar    ckpt-7d6c  (added to existing checkpoint on e4f5g6h)
skipped:
  baz    (no commits yet)
  qux    (already linked: ckpt-c97b)

提醒用户：关联操作会修改HEAD提交，因此每个被修改的仓库的本地分支将与远程分支产生分歧。若这些分支有开放的PR，需使用强制推送（

git push --force-with-lease

）更新。

Failure modes

失败场景

Session id not resolvable: stop with a one-line message — see Step 1.
No candidate repos: ask the user which repos to crosslink.
All candidates report
would_skip_existing_in_state
: tell the user the session is already linked everywhere; no work to do.
A repo's
attach
fails mid-run after others succeeded: do not retry automatically. Report which repos succeeded vs failed and surface the failing repo's stderr. The succeeded amends are idempotent — re-running the skill is safe.
HEAD has no commits in a candidate: skip that row with
```
error: no commits yet
```
. Tell the user to make at least one commit there first.
entire session attach
fails with
Entire is disabled
: the target repo opted out. Tell the user; don't retry.

无法解析会话ID：输出单行提示信息后停止操作——详见步骤1。
无候选仓库：询问用户需要交叉关联哪些仓库。
所有候选仓库均返回
would_skip_existing_in_state
：告知用户会话已关联到所有仓库，无需执行任何操作。
部分仓库
attach
操作失败，其他仓库成功：请勿自动重试。告知用户哪些仓库成功、哪些失败，并展示失败仓库的标准错误输出。已成功的修改操作是幂等的——重新运行本技能是安全的。
候选仓库中HEAD无提交：跳过该行并标记
```
error: no commits yet
```
。告知用户需先在该仓库中至少提交一次。
entire session attach
命令返回
Entire is disabled
：目标仓库已选择退出Entire。告知用户；请勿重试。

Why this skill exists

本技能的设计初衷

Entire tracks agent sessions per repo via state stored under each repo's git common dir. When an agent runs from a higher-level folder, a sibling repo, or a non-Entire-enabled parent, none of the child repos see the session. This skill resolves the session id from the agent runtime (which always has it), discovers affected repos, previews each, then runs

entire session attach

per repo on confirmation — without amending the wrong commit or asking the user to babysit per-repo

cd

Entire通过存储在每个仓库git公共目录下的状态，按仓库追踪Agent会话。当Agent从上级文件夹、同级仓库或未启用Entire的父目录运行时，子仓库无法感知到该会话。本技能从Agent运行时（始终存储会话ID）解析会话ID，发现受影响的仓库，预览每个仓库的操作，然后在用户确认后按仓库执行

entire session attach

命令——无需担心修改错误的提交，也无需用户手动逐个切换仓库目录。