Session Bridge

session-bridge is a portable CLI and skill bundle for:

• browsing saved Codex and Claude sessions
• previewing a chosen session
• importing a snapshot packet from a past session
• forking the current live Codex or Claude session into a new terminal target

It does not restore hidden reasoning, background tasks, or live tool state. Snapshot import is not live resume, and live fork only branches the provider's visible session history.

Install

Install from this repo:

bash install.sh

Or with npm:

npx session-bridge-skill install

This installs:

• Codex skill: ~/.agents/skills/session-bridge
• Claude skill: ~/.claude/skills/session-bridge
• Claude slash command: ~/.claude/commands/session-bridge.md

On first install, the CLI asks which terminal target should be used for fork-current and saves it here:

~/.session-bridge/config.json

You can skip the prompt and set it directly:

session-bridge install --terminal cmux --no-prompt

Supported terminal targets:

• cmux
• ghostty
• iterm
• terminal
• command for printing the command only

Main Commands

1. List saved sessions

All recent sessions:

session-bridge list --source all --limit 20

Only Codex:

session-bridge list --source codex --limit 20

Only Claude:

session-bridge list --source claude --limit 20

Filter by keyword:

session-bridge list --source all --query handybus --limit 20

JSON output:

session-bridge list --source all --limit 20 --json

2. Preview a saved session

By list index:

session-bridge preview 3 --source all --messages 8

By session id prefix:

session-bridge preview 019d23c7 --source codex --messages 8

3. Build a snapshot packet from a saved session

session-bridge pack 3 --source all --messages 12

This writes a markdown packet under:

.omx/artifacts/session-bridge-<source>-<session>.md

Use this when you want to continue from an old session without attaching to its live runtime.

Fork The Current Live Session

fork-current supports both Codex and Claude.

Provider detection order:

1. explicit --provider
2. CODEX_THREAD_ID
3. CLAUDE_SESSION_ID

Default usage:

session-bridge fork-current

With a first prompt:

session-bridge fork-current "continue from here, but focus only on release notes"

Force Codex:

session-bridge fork-current --provider codex

Force Claude:

session-bridge fork-current --provider claude

Print the exact command without launching:

session-bridge fork-current --terminal command

Codex behavior

Codex uses:

codex fork ...

This creates a branched Codex session with a new session ID.

Claude behavior

Claude uses:

claude --resume <session-id> --fork-session

This creates a branched Claude session from the current Claude conversation when CLAUDE_SESSION_ID is available.

Terminal Behavior

cmux

cmux opens a real new cmux window, creates a new workspace there, and selects that workspace so the forked session is actually visible.

Ghostty, iTerm, Terminal.app

These targets open a new app window and run the generated fork command inside it.

command

This target does not open anything. It prints the exact command you can run manually.

Typical Workflows

Continue from an old session snapshot

session-bridge list --source all --limit 10
session-bridge preview 2 --source all --messages 8
session-bridge pack 2 --source all --messages 12

Branch the current live Codex session into cmux

session-bridge fork-current --provider codex --terminal cmux

Branch the current live Claude session into the configured target

session-bridge fork-current --provider claude

CLI Help

session-bridge --help
session-bridge doctor

doctor shows:

• configured terminal target
• detected current provider
• detected current Codex thread
• detected current Claude session

Version Sync

The skill version is defined in:

skill/SKILL.md

Useful commands:

npm run version:check
npm run version:sync
npm test

npm pack and npm publish also run the sync step automatically through prepack.