Agent Switcher

Agent Switcher is a VS Code extension that moves an active coding conversation between Claude Code and OpenAI Codex. Pick a recent chat, choose where it should continue, review one compact confirmation, and the destination agent opens with the visible conversation plus fresh repository context.

The selected chat is primary. Git and workspace information support it. Agent Switcher never attempts to capture or transfer hidden model reasoning.

Primary flow

Run Agent Switcher: Handoff Chat from the Status Bar, Activity Bar, or Command Palette:

Click Agent Switcher
        ↓
Select a Claude Code or Codex conversation
        ↓
Select the destination agent
        ↓
Review the compact handoff
        ↓
Confirm
        ↓
A new destination conversation opens

The source picker places conversations for the current workspace first, then sorts other chats by recent activity. Each row shows the provider, title, activity time, workspace, session identifier, and message count when the provider exposes one.

The other provider is the first destination choice. Starting a separate conversation in the same provider remains available as a secondary choice.

Conversation discovery

Claude Code

Agent Switcher uses the official Claude Agent SDK listSessions() and getSessionMessages() interfaces. These read the locally persisted Claude Code sessions that the SDK supports. Agent Switcher includes visible user/assistant text and visible tool activity while explicitly ignoring thinking blocks.

OpenAI Codex

Agent Switcher starts the documented Codex App Server over local stdio and uses:

• thread/list for recent conversations
• thread/read with includeTurns for the selected transcript
• thread/start to allocate a known destination thread ID

Only user messages, agent messages, visible plans, command activity, and changed-file activity are serialized. Stored reasoning items are never transferred.

Agent Switcher-captured visible messages are used only as a final fallback when a provider's primary discovery interface cannot supply a session.

Handoff content

The default handoff mode is full visible chat. Messages stay in their original order:

PRIOR CONVERSATION FROM CLAUDE CODE

USER:
The auth refresh fails when two requests happen together.

CLAUDE CODE:
I found the competing refresh calls in auth.service.ts.

After the transcript, Agent Switcher adds:

• Current workspace and active file
• Git branch and status
• Staged and unstaged diffs
• Changed files
• Relevant root instruction files
• The existing cross-agent conversation path
• Continuation and repository-safety instructions

The receiving agent is told to verify all transferred claims against the current repository.

Compact confirmation

The normal preview shows:

• Source provider and conversation
• Destination provider
• Visible message count
• Repository name
• Additional Git/file context
• A concise cross-provider security statement

Review details expands the exact generated prompt, estimated size, and redaction count. Users do not normally need to edit files, prompts, or context sections.

Security

Before preview, Agent Switcher:

1. Excludes known-sensitive paths such as .env*, private keys, credential JSON, and secret directories.
2. Redacts common bearer tokens, provider tokens, JWTs, database passwords, cloud credentials, private-key blocks, and named secrets from chat and repository text.
3. Omits Claude thinking blocks and Codex reasoning items.
4. Keeps provider authentication in the official provider tools.
5. Leaves each destination agent's normal permission and approval flow in place.

The preview states exactly how many visible messages will move between providers. Redaction is defense in depth, so Review details remains available before every send.

Destination sessions

Every unified handoff starts a new destination chat by default.

• Claude Code receives a generated session UUID and opens through the documented --session-id CLI option.
• Codex opens the interactive CLI with the generated handoff and lets the CLI create the session. codex resume <id> is used only when a rollout for that id already exists under CODEX_HOME/sessions, because the CLI cannot resume an id it has never written to disk. A recorded id with no rollout starts a fresh session instead of failing the launch.

The terminal is focused immediately. Agent Switcher records source and destination identifiers in a logical timeline:

Claude session A
        ↓
Codex thread B
        ↓
Claude session C

This mapping lives in .agentbridge/bridge.json and appears under Conversation path in the sidebar.

Automatic fallback

If no readable chats are found, Agent Switcher offers:

• Paste a Claude conversation
• Paste a Codex conversation
• Generate a workspace-only handoff
• Cancel

If a selected Claude transcript cannot be read, it also offers an export path. Paste fallback uses a multiline editor and still goes through redaction and preview.

Local state

.agentbridge/
  task.json       Canonical logical task facts and current repository snapshot
  bridge.json     Recent providers, conversation IDs, and task/session mappings
  HANDOFF.md      Latest generated transfer, also used for provider launch
  history/        Compact handoff metadata and context hashes

.agentbridge/ is added to .gitignore by default. History records do not duplicate every full prompt.

Commands

The sidebar deliberately presents Handoff Chat as the obvious first action. Older directional commands remain secondary for compatibility and manual workflows.

Requirements

• VS Code 1.96 or newer
• Node.js 20 or newer for development
• Git for repository context

Provider CLIs

Agent Switcher launches the official provider CLIs. It does not bundle them, and the IDE extensions for Claude Code and Codex do not install them either — the standalone CLI is a separate install. Both CLIs must be installed for a handoff in either direction to open. They do not have to be on the extension host's PATH: Agent Switcher looks for them itself, and the path can always be set by hand.

npm install -g @anthropic-ai/claude-code   # https://code.claude.com/docs/en/cli-reference
npm install -g @openai/codex               # https://developers.openai.com/codex/cli/reference

Verify before using Agent Switcher, then reload the VS Code window:

claude --version
codex --version

Each CLI must also be signed in through its own official login flow (claude and codex login). Agent Switcher never handles provider credentials; it reports authentication state and leaves login to the provider tool.

Claude session discovery is supplied by the official Agent SDK dependency. Codex discovery requires a CLI version with the documented App Server.

How the CLIs are located

The VS Code extension host does not always inherit a customized login-shell PATH, particularly on macOS when VS Code is launched from the Dock or Finder rather than from a terminal, and on Windows where npm installs the CLIs as .cmd shims. Agent Switcher therefore does not rely on PATH alone. For each provider it tries, in order:

1. The agentbridge.<provider>.executable setting, when set.
2. The command name on the extension host's PATH.
3. The usual install locations — ~/.claude/local, ~/.codex/bin, ~/.local/bin, Homebrew, ~/.cargo/bin, ~/.bun/bin, Volta, pnpm, %APPDATA%\npm, and the per-runtime bin directories of nvm, fnm, mise, and asdf.
4. command -v inside your own login shell, which catches installs only a shell rc file knows about.

The resolved location is cached and shown in the sidebar tooltip under Providers.

If a CLI is still not found

Run Agent Switcher: Set CLI Path (also reachable by clicking the provider row in the sidebar) and either detect again, browse for the binary, or type the path:

which codex    # e.g. /Users/you/.local/bin/codex

{
  "agentbridge.codex.executable": "/Users/you/.local/bin/codex",
  "agentbridge.claude.executable": "~/.claude/local/claude"
}

~ and environment variables are expanded, and executable changes take effect immediately — no window reload. Leave a setting empty to go back to automatic detection.

Handoff failure messages

A failed launch never discards work — the generated transfer stays at .agentbridge/HANDOFF.md and the next attempt reuses it.

Run locally

npm install
npm run check

Open this repository in VS Code and press F5. In the Extension Development Host, open a repository and click Agent Switcher: Handoff in the Status Bar.

To build a VSIX:

npm run package

Configuration

Executable changes apply immediately. ~ and environment variables are expanded, and both executable settings are machine-overridable so a machine-specific path does not follow a shared workspace.

Architecture

Handoff Chat command
        ↓
ConversationProvider
  ├─ Claude Agent SDK
  └─ Codex App Server
        ↓
Source Quick Pick → Destination Quick Pick
        ↓
Full visible transcript + fresh repository context
        ↓
Redaction → Compact preview → Confirmation
        ↓
AgentAdapter → New official provider session
        ↓
Task mapping + handoff history

Provider discovery, provider launch, context collection, security, state, and UI remain isolated behind explicit interfaces.

Development

npm run build
npm test
npm run check

The automated suite uses mocked provider terminals, a mock Codex App Server, and temporary Git repositories. It does not require paid provider access or mutate real conversations.

Scope

Agent Switcher does not run autonomous agent loops, bypass provider approvals, merge conflicting edits, sync conversations to a cloud service, store credentials, scrape provider UI, or transfer private reasoning.