# Cross-Harness Session Resume

## Overview

AnyFS enables transferring an agent session from one harness to another. A user working
in Claude Code can hand off the session to Codex CLI, Gemini CLI, or Cursor - and the
new agent picks up where the previous one left off.

## Two Resume Modes

### Native Resume (Default, `--native`)

Generates a real native transcript file that the target client can load as a previous
session. Provides full tool call history for replay.

```bash
anyfs resume session.jsonl --target codex-cli
```

**How it works:**
1. Parse source transcript into Canonical format (UASF)
2. Export to target's native format
3. Write native session files to target's session directory

**Claude Code native export**: Generates `.jsonl` + session metadata in
`~/.claude/projects/<encoded-workspace>/`

**Codex CLI native export**: Similar JSONL generation for Codex session format.

### Context Injection (`--context-only`)

Compresses the transcript into a summary and injects it into the target's instruction file.
Less fidelity but works with all targets.

```bash
anyfs resume session.jsonl --target cursor --context-only
```

**Injection targets:**
- Claude Code: Appends to `CLAUDE.md` in workspace
- OpenClaw: Writes a native session store entry + transcript under `~/.openclaw/agents/<agent>/sessions/`
- OpenCode: Imports a native session into the local OpenCode store via `opencode import`
- Cursor: Creates `.cursor/rules/resumed-session.mdc`
- Gemini: Appends to `GEMINI.md` in workspace
- Codex: Appends to `AGENTS.md` in workspace

**Context format** (max 8000 chars):
```
## Resumed Session Context
Previous session from claude-code (model: claude-opus-4-6)

### User Requests
- [summary of user messages]

### Key Decisions
- [important choices made]

### Files Touched
- path/to/file.py (edited)
- path/to/other.py (created)

### Commands Executed
- npm install
- pytest

### Errors Encountered
- [any errors and resolutions]
```

## Canonical Transcript Format (UASF)

All agent transcripts are parsed into a universal format:

```python
CanonicalTranscript:
  session:
    id: str                    # Session UUID
    agent: str                 # "claude-code", "codex-cli", etc.
    model: str                 # "claude-opus-4-6", "gpt-4o", etc.
    cwd: str                   # Working directory
    git_branch: str | None     # Git branch at session start
    started_at: str            # ISO timestamp
    version: str               # Format version

  events: list[TranscriptEvent]
    # Each event is one of:
    - user_message(content: str)
    - assistant_text(content: str)
    - thinking(content: str)
    - file_read(path: str, content: str | None)
    - file_edit(path: str, old: str, new: str)
    - file_write(path: str, content: str)
    - shell_command(command: str, output: str | None, exit_code: int | None)
    - code_search(tool: str, query: str, results: str | None)
    - error(message: str)
    - file_snapshot(path: str, content: str)
```

## Parser Details

### Claude Code Parser

Parses `.jsonl` files from `~/.claude/projects/<workspace>/`:

- Entry types: `system`, `user`, `assistant`, `file-history-snapshot`
- Tool mapping: `Bash` -> `shell_command`, `Read` -> `file_read`, `Edit` -> `file_edit`,
  `Write` -> `file_write`, `Grep/Glob/WebSearch/WebFetch` -> `code_search`
- Enriches tool events with results via `tool_use_id` matching
- Handles subagent sessions via subdirectory structure

### Codex CLI Parser

Parses `.jsonl` with event types: `event_msg`, `input_text`, `output_text`.

### Gemini CLI Parser

Parses file-based session format.

## Usage Examples

### Claude Code -> Codex CLI (Native)

```bash
# Find the Claude Code session file
ls ~/.claude/projects/-home-user-myproject/

# Resume in Codex
anyfs resume ~/.claude/projects/-home-user-myproject/abc123.jsonl \
  --target codex-cli --source claude-code --workspace /home/user/myproject
```

### Codex CLI -> Claude Code (Native)

```bash
anyfs resume codex-session.jsonl --target claude-code --workspace .
```

### Any -> Cursor (Context Only)

```bash
# Cursor doesn't support native transcript import, so use context injection
anyfs resume session.jsonl --target cursor --context-only --workspace .
# Creates .cursor/rules/resumed-session.mdc
```

### Claude Code -> Gemini CLI (Context Only)

```bash
anyfs resume session.jsonl --target gemini-cli --context-only --workspace .
# Creates/appends to GEMINI.md
```

## Combining Share + Resume

Full cross-client collaboration flow:

```bash
# User A (Claude Code): Capture and share session
anyfs quick-share -w . -n process -p SharedPass

# User B (Codex CLI): Receive and resume
anyfs share open https://storage.anyfs.ai/raw/<cid> -p SharedPass
# -> Outputs process.json containing the transcript

# Extract the transcript file from the share and resume
anyfs resume process.json --target codex-cli --workspace .
```

## Limitations

- Native export only works for Claude Code <-> Codex CLI bidirectional
- Gemini CLI and Cursor only support context injection (summary)
- Context injection loses tool call details (reduced fidelity)
- Live/real-time session sync is not implemented (manual trigger only)
- Source auto-detection may fail for ambiguous formats; use `--source` explicitly