Repository navigation
docs: document forking and handing off agent sessions #8013
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
982c457
7db74da
414911f
48aae20
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -56,6 +56,7 @@ Go to **Settings → Agents** to customize launch behavior for each built-in age | |
| - **Prompt Command Suffix** - Optional flags appended after the prompt payload | ||
| - **Task Prompt Template** - Template used when launching an agent from a task | ||
| - **Resume Args** - Arguments used to restore a killed session by its id (e.g. `--resume`) | ||
| - **Fork Args** - Arguments used to clone a session by its id. Put `{sessionId}` where the id belongs (e.g. `--resume {sessionId} --fork-session`); leave empty if the agent cannot fork | ||
| - **Model Override** - Optional model override for Superset Chat | ||
| - **Reset to Defaults** - Restore the shipped configuration for that agent | ||
|
|
||
|
|
@@ -76,17 +77,11 @@ When launching an agent from a task, the **Auto-run command** toggle controls wh | |
|
|
||
| The setting is remembered between sessions. | ||
|
|
||
| ## Resume Interrupted Sessions | ||
| ## Agent Sessions & Forking | ||
|
|
||
| If an agent's terminal dies under it (a crash, a reboot, a killed process), Superset resumes the session automatically: the pane relaunches the agent with its resume command (e.g. `claude --resume <session-id>`) and shows a "Resuming…" pill while it happens. Only unexpected deaths qualify: sessions you close or kill deliberately, and agents that exited cleanly, stay down. | ||
| <a id="resume-interrupted-sessions" /> | ||
|
|
||
| If the resume fails, the pill turns into "Failed to resume" with a **Retry** button and a dismiss control. | ||
|
|
||
| Works for agents with an id-based resume command (the **Resume Args** field under **Settings → Agents**). From the CLI: | ||
|
|
||
| ```bash | ||
| superset agents create --workspace ws_… --agent claude --resume-session <sessionId> | ||
| ``` | ||
| Resume an interrupted session, fork a session, or hand its work to another agent. See [Agent Sessions & Forking](/agent-sessions). | ||
|
Comment on lines
+80
to
+84
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Prompt To Fix With AIThis is a comment left during a code review.
Path: apps/docs/content/docs/agent-integration.mdx
Line: 80-82
Comment:
**Existing recovery anchor disappears** Replacing the “Resume Interrupted Sessions” heading removes its published anchor. The link within these docs was updated, but existing bookmarks and external links to `/agent-integration#resume-interrupted-sessions` no longer take readers to the instructions. Preserve an anchor at the old location that directs readers to the new page.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly. |
||
|
|
||
| ## Parallel Agents | ||
|
|
||
|
|
||
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,80 @@ | ||||||||||||||||||||||||||
| --- | ||||||||||||||||||||||||||
| title: Agent Sessions & Forking | ||||||||||||||||||||||||||
| description: Resume, fork, and hand off agent sessions | ||||||||||||||||||||||||||
| --- | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| An agent session is one agent conversation running in one terminal. Superset can bring a session back after its terminal dies, copy it into a new session of the same agent, or pass its recent context to a different agent. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ## Resume Interrupted Sessions | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| If an agent's terminal dies under it (a crash, a reboot, a killed process), Superset resumes the session automatically: the pane relaunches the agent with its resume command (e.g. `claude --resume <session-id>`) and shows a "Resuming…" pill while it happens. Only unexpected deaths qualify: sessions you close or kill deliberately, and agents that exited cleanly, stay down. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| If the resume fails, the pill turns into "Failed to resume" with a **Retry** button and a dismiss control. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| Works for agents with an id-based resume command (the **Resume Args** field under **Settings → Agents**). From the CLI: | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ```bash | ||||||||||||||||||||||||||
| superset agents create --workspace ws_… --agent claude --resume-session <sessionId> | ||||||||||||||||||||||||||
| ``` | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ## Fork and Hand Off Sessions | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| The fork icon in an agent terminal's header opens two actions. Both open the new session in a split pane or a new tab. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
|  | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| - **Continue with another agent** - Starts a fresh session of the agent you pick, seeded with this terminal's recent context. Use it when a session is stuck, out of context, or the wrong tool for the job. The dialog shows how many characters (and about how many tokens) it will send before you continue. | ||||||||||||||||||||||||||
| - **Fork session** - Starts a native copy of this session in the same agent, with the same conversation. The original session keeps running unchanged. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ### Fork | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| Fork uses the agent's own fork command, so the copy has the full conversation. Built-in agents that can fork, with the fork part of each command: | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| | Agent | Fork command | | ||||||||||||||||||||||||||
| | --- | --- | | ||||||||||||||||||||||||||
| | Claude Code | `claude --resume <id> --fork-session` | | ||||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P3: The Fork command table columns read as the exact commands Superset runs, but they drop flags that are part of the built-in commands. In Prompt for AI agents |
||||||||||||||||||||||||||
| | Codex | `codex fork <id>` | | ||||||||||||||||||||||||||
| | OpenCode | `opencode --session <id> --fork` | | ||||||||||||||||||||||||||
| | Pi | `pi --fork <id>` | | ||||||||||||||||||||||||||
| | Grok | `grok --resume <id> --fork-session` | | ||||||||||||||||||||||||||
|
Comment on lines
+33
to
+39
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Prompt To Fix With AIThis is a comment left during a code review.
Path: apps/docs/content/docs/agent-sessions.mdx
Line: 33-39
Comment:
**Fork commands omit permission flags** The table reads as the commands Superset runs, but its Claude, Codex, and Grok entries leave out flags that change approval or permission behavior. Someone using the table to understand a fork’s permissions will miss those flags. Show the full built-in commands or label these as abbreviated examples.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time! |
||||||||||||||||||||||||||
| | Droid | `droid --fork <id>` | | ||||||||||||||||||||||||||
|
Comment on lines
+35
to
+40
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- documented commands ---'
sed -n '31,42p' apps/docs/content/docs/agent-sessions.mdx
printf '%s\n' '--- built-in fork command definitions ---'
sed -n '55,105p' packages/shared/src/builtin-terminal-agents.ts
sed -n '176,195p' packages/shared/src/builtin-terminal-agents.tsRepository: superset-sh/superset Length of output: 3444 Synchronize the three documented fork commands with the built-in commands. The documented Claude Code, Codex, and Grok commands omit flags used by Superset's built-in fork commands. Copying the documented commands can change permission, approval, sandbox, and hook-trust behavior, or prevent an unattended fork. Suggested fix-| Claude Code | `claude --resume <id> --fork-session` |
-| Codex | `codex fork <id>` |
+| Claude Code | `claude --dangerously-skip-permissions --resume <id> --fork-session` |
+| Codex | `codex --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust fork <id>` |
...
-| Grok | `grok --resume <id> --fork-session` |
+| Grok | `grok --always-approve --resume <id> --fork-session` |📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| Superset also passes the agent's launch flags, such as `--dangerously-skip-permissions` for Claude Code, so a fork runs with the same permissions as a new session. **Settings → Agents** shows each agent's command and fork args. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| For other agents, set **Fork Args** under **Settings → Agents**. **Fork session** is disabled until Superset knows the agent's session id, and for agents without fork args. For Claude Code, Codex, OpenCode, and Pi, Superset refuses the fork if the agent has deleted the source session. For other agents, Superset cannot check, so the new pane opens and the agent reports the missing session there. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| A fork copies the conversation, not the files. Both sessions work in the same workspace. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ### Continue with another agent | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| The new session gets a prompt that contains the last 36,000 characters of this terminal's context, marked as read-only history. The prompt tells the agent to check `git status` and the files first, because the workspace, not the transcript, is the source of truth. For Claude Code and Codex, Superset reads the agent's own saved conversation when it can. Otherwise it reads the terminal's recorded output stream, not only the visible screen. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| <Callout type="warn"> | ||||||||||||||||||||||||||
| A handoff sends terminal output to the target agent's provider. Superset removes terminal control codes but does not redact anything, so tokens, keys, or connection strings that a command printed go with it. If the session showed credentials, ask the agent for a summary and start the new agent with that instead. | ||||||||||||||||||||||||||
| </Callout> | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ## Find Session and Terminal IDs | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| Click the copy icon in an agent terminal's header (**Copy IDs**): | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| - **Copy agent session ID** - The agent's own session id, used by `--resume-session` and `--fork-session` | ||||||||||||||||||||||||||
| - **Copy terminal ID** - The Superset terminal id, used by `--from-terminal` and `superset agents read` | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ## From the CLI | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ```bash | ||||||||||||||||||||||||||
| # Fork a session | ||||||||||||||||||||||||||
| superset agents create --workspace <workspace-id> --agent claude --fork-session <agent-session-id> | ||||||||||||||||||||||||||
| # Continue in another agent | ||||||||||||||||||||||||||
| superset agents create --workspace <workspace-id> --agent codex --from-terminal <terminal-id> | ||||||||||||||||||||||||||
| ``` | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| `--from-terminal` builds its own prompt, so it does not accept `--prompt`. Use `--context-chars` to send less than 36,000 characters. See [`agents create`](/cli/cli-reference#agents). | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ## Read an Agent's Transcript | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| `superset agents read` returns the agent's saved conversation, including what scrolled off a full-screen interface. Superset can read saved transcripts for Claude Code and Codex. The command fails for other agents, and when the saved transcript is missing. It does not fall back to terminal output. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| ```bash | ||||||||||||||||||||||||||
| superset agents read --local --workspace <workspace-id> --terminal <terminal-id> | ||||||||||||||||||||||||||
| ``` | ||||||||||||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2: Preserve the
resume-interrupted-sessionsanchor here and link it to the new instructions; replacing the heading breaks existing bookmarks to/agent-integration#resume-interrupted-sessions.Prompt for AI agents