OmniSession

Search local coding-agent sessions and continue them in another harness.

Website · Compatibility · Design

OmniSession is alpha. Transfers leave source sessions unchanged, create a separate target session, and verify imported history before launch. Unsupported versions use a short handoff when available or stay out of target picker. Deletion is separate, explicit, and limited to selected native session.

Install

Linux and macOS remain default:

curl -fsSL https://raw.githubusercontent.com/bvolpato/omnisession/main/install.sh | sh

Windows x86-64 Preview, from PowerShell:

irm https://raw.githubusercontent.com/bvolpato/omnisession/main/install.ps1 | iex

Both installers verify release checksum and install omni. Linux and macOS installation also adds provider shims. Windows installer is binary-only. To opt into compiled provider aliases, run this in PowerShell, then follow printed PATH guidance:

omni shim install --bin-dir "$env:LOCALAPPDATA\OmniSession\bin"

Before rerunning Windows installer for an upgrade, remove hard-link aliases and reinstall them afterward:

omni shim uninstall --bin-dir "$env:LOCALAPPDATA\OmniSession\bin"
irm https://raw.githubusercontent.com/bvolpato/omnisession/main/install.ps1 | iex
omni shim install --bin-dir "$env:LOCALAPPDATA\OmniSession\bin"

Restart shell after installer changes PATH. Windows packaging, installer, CLI, and shims run in native Windows CI. Installed Codex, OpenCode, and Grok checks run without credentials; broader provider fidelity remains provisional. WSL is a separate Linux environment; use Linux installer inside WSL.

Check this machine

omni adapters
omni --json adapters

Adapter status separates declared platform support from detected session stores, launchers, selected transfer route, and runtime validation still required. Discovery reads paths and bounded static metadata; it does not launch an agent or desktop app. Version, schema, active-writer, rollback, and read-back gates still run when you request a transfer.

Pick a session

omni

NEW SESSION starts a clean session in any installed agent with a supported clean-session launcher. Type to filter by title, message, ID, directory, branch, or provider. Current workspace appears first; Tab includes every workspace. Select a session, then choose where it should open.

Delete removes supported sessions from native source store. Confirm with y, cancel with n, or press a to skip later confirmations during current picker run.

Related sessions stay grouped across agents. Selection panel shows workspace, branch, trajectory size, model, reasoning mode, token usage, and conversation edges when recorded. Full-text results show matching context and highlight search terms.

Picker checks for releases in background. Footer shows installed version and offers Ctrl+U when an update is available. Confirmation shows executable path. Package-manager installs still update through their manager. Set OMNI_NO_UPDATE_CHECK=1 to turn check off.

Resume directly

omni resume <session> --in codex

Bare session IDs work when unique. Add provider when needed:

omni resume claude:<session-id> --in codex

Fork without changing source session. Omit --in to choose target interactively:

omni fork <session>
omni fork <session> --in codex

Export visible history for manual use:

omni markdown <session> -o session.md

Run omni --help for diagnostics, shims, bundles, and advanced commands.

Supported agents

• Codex
• Claude Code
• OpenCode
• Pi
• Grok
• Cursor IDE
• Cursor Agent
• Antigravity CLI
• Hermes

Picker shows runnable targets found on current machine. Release binaries and installer support Linux and macOS on x86-64 and ARM64. Native Windows x86-64 release and PowerShell installer are preview. Windows packaging, CLI, and shims run in native CI; provider fidelity remains capability-specific and provisional. WSL is treated as a separate Linux environment. docs/COMPATIBILITY.md lists version signals and transfer paths. Newer versions remain enabled unless structural validation or read-back fails. claude and claude-code are interchangeable in session references and provider flags.

What moves

OmniSession preserves ordered user and assistant messages plus bounded tool activity. Same-provider sessions use native resume and fork paths when available. Cross-provider transfers prefer documented imports, then verified native writers for supported private formats.

Tool calls and shell commands remain historical text. They are never replayed. Approvals, credentials, hidden reasoning, and provider permission state stay out.

Portable imports become durable local sources addressed by exact imported:<bundle-uuid> locators. They remain searchable and resumable after original native store is unavailable, while preserving original provider and session provenance.

Safety

• Transfers do not write source provider stores. Deletion requires Delete plus confirmation and removes only selected native ID.
• Cross-agent transfers create a new target session ID.
• OmniSession reads target back before launch.
• Failed target writes roll back only records OmniSession created.
• Workspace selection or exact session ID decides routing. Recency does not.
• Local index stores bounded, redacted content from sessions OmniSession already read. Oversized trajectories retain first and last 5 MiB of visible UTF-8 context in overlapping chunks, with coverage reported as partial.

Set OMNI_BYPASS=1 to bypass installed shims for one provider command. OmniSession data lives in ~/.omnisession/; set OMNISESSION_HOME to move it.

Development

cargo fmt --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace --all-features
pnpm --dir website install --frozen-lockfile
pnpm --dir website typecheck
NEXT_PUBLIC_BASE_PATH=/omnisession pnpm --dir website build

MIT licensed.