--- name: fork-agent-pattern-2026-07-02 description: "How to fork a Claude Code agent by session-cloning: cp JSONL + new UUID + --resume in a new tmux window. Preserves inherited context; scope diverges going forward. Helper: agents_stuff/fork_agent.sh" metadata: node_type: memory type: feedback originSessionId: cd07777c-8add-4afc-9cb9-9113caa0331f --- **When to use:** an existing agent has too much context (multiple domains, growing session file), and you want to split off a specialty domain without losing the accumulated understanding. **Contrast with alternatives:** - **Sub-Task (Task tool):** right for one-shots, wrong for durable specialties. Sub-Tasks don't persist across sessions. - **Fresh new agent + bootstrap prompt:** loses all inherited knowledge; slow to reach parity. - **Session clone (this pattern):** inherits full context byte-for-byte; only scope diverges going forward. **Mechanism:** Claude Code sessions are just JSONL files at `~/.claude/projects//.jsonl` (cwd-encoded = `/` and `_` replaced with `-`). A "fork" is literally: ```bash new_uuid=$(uuidgen) cp .jsonl .jsonl # same project dir tmux new-window -t agents -n -c tmux send-keys "claude --resume $new_uuid --dangerously-skip-permissions" Enter ``` Same cwd matters — the project-dir encoding maps cwd → project. Different cwd means Claude Code won't find the cloned file. **Helper script:** `agents_stuff/fork_agent.sh ` — does the mechanical part (locate UUID from resume_fleet WINDOW_PLAN, clone JSONL, launch new tmux window, print a checklist for the manual work). **Judgment work (NOT automated by the script):** 1. `agents//{ROLE.md, inbox, outbox, status}` — with scope rules + files-convention rules (never edit `agents//*`) 2. `vault/fleet/agents//{overview,tasks,memory}.md` — personal slice 3. Shared vault domain slice for joint knowledge — e.g. `vault/para/yam/` when splitting yams → yam_sim; both agents contribute, cross-ping the other's inbox on update 4. Fleet-config entries: `config.yaml`, `para/.agents/config.yaml`, `GUIDELINES.md` roster table 5. `resume_fleet.sh` WINDOW_PLAN entry with the **explicit new UUID** (blank/autodiscover would find the source's bootstrap signature and misresume as the wrong session — always pin the cloned UUID) 6. Divergence message to new agent (scope, files rule, bootstrap task: mine inherited memory to shared vault domain doc) 7. Heads-up message to source agent (stop touching split-off scope; cross-ping convention) **Gotchas:** - **Doesn't reduce current context.** Both agents start at the same JSONL size. Only *going forward* does each trim toward its focus (via compactions). If the goal is immediate context relief, this alone isn't the tool — consider having source /compact first, then fork the compacted session. - **Identity ambiguity — the classic failure mode.** The new agent *remembers being* the source. It routinely re-reads the divergence message and acts as the SOURCE acknowledging the fork ("great, I'll drop 's scope and stand by") rather than as the child ADOPTING the new scope. Seen concretely on financials fork 2026-07-06: the financials pane spent multiple turns saying "continuing on personal-advisor / Brandon / notes-sync / values scope" — that's life_manager's scope, not financials's. Cameron correctly saw this as "the financials tab isn't being financials." Mitigation in the divergence message (mandatory for future forks): include an explicit self-correction clause like *"If you find yourself acknowledging 's scope or saying you'll drop 's work — STOP. You ARE . The drop-off already happened via the fork. Re-read your ROLE.md and start doing 's bootstrap task."* Also: the new agent should verify its identity by writing to files under `agents//` (not `agents//`) as an early bootstrap action — if it can't do that without confusion, it's still stuck as the source. - **Persistent shells belong to source.** The new agent inherits memory of shells it doesn't actually own. Tell it explicitly: spawn your own. - **Filesystem project-dir encoding.** cwd `/data/cameron` encodes to `-data-cameron`; cwd `/data/cameron/agents_stuff` encodes to `-data-cameron-agents-stuff`. Copy the JSONL to the SAME project dir as the source, and use the SAME cwd for the new tmux window — otherwise `--resume` won't find it. - **Mtime autodiscover breaks after forking.** Once you've cloned a source, the clone shares the source's bootstrap signature ("you are the '' agent") — and the clone's mtime becomes newer than the original as its cloned agent writes to it. So autodiscover-by-newest-signature-match picks up the CLONE, not the original. Fix: always resolve source UUID via **live tmux discovery** — ask the source pane's actual `claude --resume ` process what UUID it's using. Fall back to a **ROSTER pin** if the source isn't running. Never trust mtime-signature autodiscover after forks exist. `fork_agent.sh` (2026-07-02 hardening) tries live tmux → ROSTER → mtime, in that order. **Also pin the source's own UUID in resume_fleet.sh WINDOW_PLAN after the first fork**, so a reboot resumes the correct session rather than any clone. **Precedent:** yams → yam_sim on 2026-07-02. yams's 153MB session cloned; yam_sim owns MuJoCo simulation, sim training, sim-side fiducial exoskeleton, sim2real, sim-derived data. yams keeps real-robot side. Shared domain vault at `vault/para/yam/` with cross-ping-on-update convention. Coordination worked cleanly on day 0 — yams voluntarily wrote a handoff into yam_sim's inbox listing open sim tasks (Anzu tumbler + banana imports, `record_sim.py` skeleton). **How to apply:** - When Cameron says an agent has "too much context" or wants to split off a domain, offer this pattern (not sub-Task, not fresh spawn). - Draft the ROLE.md + divergence message carefully — this is where identity ambiguity is prevented. - **ALWAYS use resume_fleet.sh WINDOW_PLAN with explicit UUID for cloned sessions** — never rely on autodiscover for a fork. - Related: [[code-lives-on-lab-2026-06-23]] for path conventions; [[persian-agent-shipped-2026-06-22]] and [[fleet-dashboard-shipped-2026-06-27]] as precedents for the roster-add pattern the checklist references.