Session history and restore

Superconductor attaches session state to the worktree that produced it. When you switch tasks, quit the app, or return later, Superconductor reopens the relevant terminal or chat surface with the provider session it can resume.

What gets restored

Session restore stores:

• The workspace, project, and worktree path.
• The tab type, such as terminal or chat.
• The provider used for the session.
• The provider’s resume identifier, when the provider exposes one.
• The tab title and local session metadata.

Providers expose different resume behavior. Some assign a deterministic session ID at tab creation. Others expose a session ID only through hooks or their own history files after the agent starts. Superconductor stores the available provider binding and falls back to a fresh session when it cannot validate the old one.

Provider behavior

Resume support depends on the provider CLI:

• Claude, Codex, Copilot, Cursor Agent, Gemini, Grok, OpenCode, and Pi each accept provider-specific resume arguments when Superconductor has a usable session ID or path.
• Kiro falls back to a fresh terminal session.

History picker

The history picker reopens past provider work for the current worktree. Superconductor scopes history by workspace and worktree. Use the picker to:

• Reopen an agent conversation after closing a tab.
• Review a previous run before prompting again.
• Restore a session after switching tasks.

Tab titles

From a Superconductor-launched terminal or local API chat session, set the current tab’s title with:

sc tab title "Fix Auth Timeout"

Limits

Restore depends on the provider CLI and the local data it keeps. If a provider deletes its history, changes its resume format, or cannot validate an old session, Superconductor opens a fresh session rather than pretend the old context is still live.

What Superconductor owns

Session restore coordinates local app state with provider-owned CLI state. Superconductor owns:

• Workspace and worktree identity.
• Tab order and titles.
• Terminal or chat tab metadata.
• Split layout.
• Local conversation identity.
• Local transcript and history records where available.

This state reopens the workspace, selects the worktree, and reconstructs the app layout.

What the provider owns

The agent provider owns provider session state:

• Claude Code session files.
• Codex threads.
• Gemini sessions.
• OpenCode sessions.
• Pi session files.
• Other provider-specific history or resume targets.

Superconductor stores the provider’s resume target when it can identify one. Superconductor does not rewrite the provider history store.

Fresh, cold, and warm restore

Restore takes three forms:

• Fresh open: you create a new tab or chat session.
• Warm restore: the app trusts a recently live session and reconnects quickly.
• Cold restore: the app restarted and resumes from stored provider metadata when possible.

Cold restore applies stricter checks for providers Superconductor can validate locally. For other providers, Superconductor passes the stored resume target to the provider CLI and falls back when the target is missing or the provider cannot resume it.

Why providers differ

Providers expose different resume mechanisms:

• Some accept a session ID at launch.
• Some reveal a session ID only after startup.
• Some resume from a file path.
• Some resume only the most recent session.
• Some ship native chat adapters, terminal CLIs, or both.

Two providers launched from the same worktree can therefore behave differently.

Split and PiP restore

Workspace state restores split layouts. PiP is a floating view tied to the worktree and tab content that opened it. After you switch tasks, reopen PiP from the new task to capture the new context.

When restore falls back

Superconductor opens a fresh session when:

• The provider deleted or moved its history.
• The provider changed its resume format.
• The saved resume ID is provisional or local-only.
• The provider CLI is no longer installed.
• The workspace or worktree was deleted.
• Cold restore cannot validate or use the old session.

When restore falls back, Superconductor starts a fresh session.