docs: document forking and handing off agent sessions
Merged
AV
2mo ago+99+99+01234567890123456789-11-11-01234567890123456789
Summary
- New Agent Sessions & Forking docs page (
/agent-sessions): resume interrupted sessions, the fork-icon menu (Continue with another agent, Fork session), which agents fork natively, how to find session and terminal IDs, the CLI forms, andsuperset agents read. superset agents createreference gains--fork-session,--from-terminal, and--context-chars, and--promptis no longer described as required unless--resume-sessionis set.- AI Agents now points to the new page instead of carrying the resume section; adds the Fork Args setting to its settings list.
Why / Context
Session fork and handoff shipped in #6962, but only the blog post and changelog described it. The CLI reference was also wrong: --prompt is optional with any of --resume-session, --fork-session, or --from-terminal, and rejected with --from-terminal.
Every claim comes from the code, not the marketing copy:
- Flags, mutual exclusion, prompt rules, and the 1-36000 range:
packages/cli/src/commands/agents/create/command.ts - Handoff prompt and 36,000-character budget:
packages/shared/src/terminal-session-handoff.ts - Native fork commands (Claude Code, Codex, OpenCode, Pi, Grok, Droid):
packages/shared/src/builtin-terminal-agents.ts - Fork refused for agents without fork args or when the source session is gone:
packages/host-service/src/trpc/router/agents/agents.ts - Menu, placement, the disabled Fork state, and the copy-IDs menu:
TerminalSessionHandoffMenu.tsx,TerminalIdCopyMenu.tsx - The agent's own transcript is read first for Claude Code and Codex, otherwise the recorded terminal stream:
transcriptSessioninpackages/host-service/src/terminal/terminal.ts
Where the blog post and the code disagree (the docs follow the code)
- "Continue with another agent" does not require a different agent: the picker lists every agent, including the source one.
- The blog says the handoff prefers the agent's own conversation store. That only applies to Claude Code and Codex, and only while the agent's session is still live in that terminal.
- The blog calls Droid's fork flag unverified, but the code ships it as a built-in fork command.
Testing
bun run typecheckinapps/docs(compiles the MDX)bun run buildinapps/docs, on the first commit- Dev server:
/agent-sessions,/agent-integration,/terminal-integration, and/cli/cli-referencereturn 200, and the moved anchors (#resume-interrupted-sessions,#fork-and-hand-off-sessions) resolve - Not checked in a browser. No prose lint was run: biome does not cover MDX and the repo has no vale config.
Notes
- The screenshot is copied from the changelog (
/changelog/2026-08-30-session-handoff.png). - The page URL is
/agent-sessions. The title is "Agent Sessions & Forking".
Summary by cubic
Documents session forking and handoff in a new Agent Sessions & Forking docs page, and corrects the agents create CLI reference.
- Adds the
/agent-sessionspage covering resume, the fork-icon menu, finding session and terminal IDs, andsuperset agents read(noting it needs a saved transcript). - Moves session recovery out of AI Agents, adds the Fork Args setting, and keeps the old resume anchor pointing to the new page.
- Documents
--fork-session,--from-terminal, and--context-charsonagents create;--promptis optional with any session flag and rejected with--from-terminal. - Clarifies that the fork-command table omits launch flags while Superset actually passes them, and that fork refusal applies only to agents whose transcripts Superset can read.
Summary by CodeRabbit
- Documentation
- Added guidance for resuming interrupted sessions, forking sessions within an agent, and handing recent terminal context to another agent.
- Documented the
{sessionId}placeholder and Fork Args configuration, along with supported CLI options, mode constraints, and the terminal-context limit. - Added the agent sessions guide to the documentation navigation and updated Agent Settings and terminal integration links to point to it.