Agent Switch Skill

Agent Switch Skill

Overview

Use this skill to install and drive the local agent-switch command. The command owns the capture proxy, dashboard, exports, and a Codex-facing handoff after a wrapped CLI exits.

First-Use Bootstrap

When this skill is used, first check whether the CLI is already available:

agent-switch --help

If agent-switch is missing from PATH, install it from this skill directory by running:

node scripts/install-agent-switch.js

The installer installs the bundled CLI tarball from cli/agent-switch-skill-.tgz and verifies the result with agent-switch --help. If the tarball is missing in a development checkout, the installer falls back to installing production dependencies and then running npm install -g . If installation fails because Node.js is missing or too old, tell the user to install Node.js 18 or newer and retry.

Manual Install

From the skill directory, run the included installer:

node scripts/install-agent-switch.js

Or install the bundled CLI package directly:

npm install -g cli/agent-switch-skill-0.1.0.tgz

Verify the command exists:

agent-switch --help

Run Another CLI

Use one command to delegate work to another coding CLI with capture enabled:

agent-switch claude

If the user runs agent-switch without a provider command, show a searchable TTY picker for supported CLIs. If the user names a provider explicitly, such as agent-switch codex, start that provider directly without opening a picker.

Pass arguments through normally:

agent-switch claude --resume
agent-switch codex
agent-switch codewhale
agent-switch deepseek
# Set MOONSHOT_API_KEY before using the Kimi provider.
agent-switch kimi
agent-switch run --provider openai -- my-openai-compatible-cli

If a target CLI option conflicts with an Agent Switch option, insert -- before the target option. Agent Switch removes this separator before launching the target:

agent-switch claude -- --profile target-profile
agent-switch run --provider openai -- my-cli --model model-name

Target --help, --version, --model, --format, and --health options must reach the target CLI. Agent Switch must stop parsing its own options at --.

Use agent-switch codewhale for CodeWhale, formerly DeepSeek-TUI. agent-switch deepseek and agent-switch deepseek-tui remain compatibility aliases and launch the current codewhale / codewhale-tui binaries even though upstream no longer installs the old shims.

Captured CLI runs do not open the dashboard automatically. Do not open a web page just because the user asked to use this skill, run agent-switch claude, or run another captured CLI. Only open the web UI when the user explicitly asks for the dashboard/webui, or when they run one of these commands:

agent-switch dashboard
agent-switch webui

When the child CLI exits, agent-switch prints agent-switch: returned to Codex with the exit code, latest agent-switch session, captured request count, dashboard command, and latest export command. This terminal output is the handoff back to the current Codex session.

CLI Account Profiles

Use profiles when the user wants multiple local accounts for Codex, Claude Code, or OpenCode. A profile changes only the target CLI's config/account directory; the working directory remains the current project.

Supported profile mappings:

• Codex: CODEX_HOME=~/.agent-switch/profiles/codex/, with saved auth selected from ~/.agent-switch/profiles/codex/.accounts
• Claude Code and Claude-based providers: CLAUDE_CONFIG_DIR=~/.agent-switch/profiles/claude/
• OpenCode: OPENCODE_CONFIG_DIR=~/.agent-switch/profiles/opencode/

For Codex, users can create the profile explicitly, or simply run with --profile and let agent-switch create the missing profile before auth selection:

agent-switch profile new codex/work
agent-switch codex --profile work

When agent-switch codex --profile work runs, agent-switch must:

• create ~/.agent-switch/profiles/codex/work if needed,
• read saved accounts from ~/.agent-switch/profiles/codex/.accounts,
• show a searchable TTY picker with add auth, saved auth accounts, and remove auth,
• run real codex login only when the user chooses add auth,
• save the resulting auth into the account store,
• inject the selected saved auth into ~/.agent-switch/profiles/codex/work/auth.json,
• then launch Codex in the current working directory with CODEX_HOME set to the profile directory.

Selecting remove auth must show the current saved auth list and remove the chosen saved auth from the account store.

When agent-switch codex --profile work is run with no extra Codex arguments and the profile already has saved Codex sessions, default to resuming the latest session by passing resume --last to Codex. If the profile has no saved sessions, start a new Codex session.

To inspect or choose sessions, pass Codex's resume command through:

agent-switch codex --profile work resume
agent-switch codex --profile work resume --all
agent-switch codex --profile work resume 

resume shows Codex's picker for sessions in the current working directory. resume --all shows sessions across directories.

This Codex menu must run only when --profile is present. Plain agent-switch codex must preserve the current default behavior and must not inspect, prompt for, or inject saved profile auth.

For Claude Code and OpenCode, profiles remain simple config directories. Create them explicitly:

agent-switch profile new claude/work
agent-switch claude --profile work
agent-switch claude --resume
agent-switch profile new opencode/work
agent-switch opencode --profile work

Shared mode may link or copy non-secret defaults such as Codex config.toml, Claude settings.json, skills, commands, agents, and plugins. It must not copy known auth/session files such as Codex auth.json, Claude .credentials.json, sessions, projects, todos, or history files.

Manage profiles:

agent-switch profile list
agent-switch profile path codex/work
agent-switch profile delete codex/work --yes

If no --profile flag is present, preserve the current default behavior and let the CLI use its normal global account/config.

Treat ~/.agent-switch/profiles/codex/.accounts as sensitive local data because it stores Codex auth snapshots for injection. Keep account files and injected auth.json private (0600 files and 0700 directories on POSIX; the current user's profile ACL on Windows).

Headroom Compact Mode

Do not enable compact mode unless the user explicitly asks for automatic compression, compact, or Headroom. Plain agent-switch claude must remain transparent and must not modify Claude Code requests.

When requested, use compact mode only with Claude Code based providers:

agent-switch claude --compact
agent-switch kimi --compact
agent-switch bedrock --compact
agent-switch vertex --compact

Compact mode uses the bundled headroom-ai JavaScript SDK against an external Headroom proxy. Check dependencies first:

agent-switch compact doctor

Treat a non-zero doctor exit code as a failed dependency check. The command must exit non-zero whenever the Headroom CLI, SDK, or proxy is unavailable.

If Headroom is missing, print install guidance rather than installing external Python/Rust tooling automatically:

agent-switch compact install

Default compact behavior is fail-open: if Headroom fails, agent-switch records the error and forwards the original request. Use --compact-fail closed only when the user explicitly wants uncompressed requests to stop.

RTK is intentionally not initialized in compact v1. Do not run rtk init, do not modify Claude/Codex hooks, and do not edit global agent instruction files for RTK.

Missing Target CLI

agent-switch installs and runs the capture tooling only. It does not silently install third-party coding CLIs such as Claude Code, Codex, CodeWhale, DeepSeek-TUI, or OpenCode.

If a delegated command is missing, read the CLI error and guide the user to install the target CLI first. For Claude Code, use the official install commands shown by agent-switch:

winget install Anthropic.ClaudeCode
irm https://claude.ai/install.ps1 | iex

curl -fsSL https://claude.ai/install.sh | bash
brew install --cask claude-code

After installing a target CLI, ask the user to reopen the terminal, verify the command directly, and retry through Agent Switch:

claude
agent-switch claude

For CodeWhale, the renamed DeepSeek-TUI package, guide users to install and verify:

npm install -g codewhale
codewhale doctor
agent-switch codewhale

For OpenCode, install opencode-ai. Because OpenCode may contain several providers, choose the single OpenAI-compatible upstream captured by this run:

npm install -g opencode-ai
agent-switch opencode --upstream 

Local Upstream Troubleshooting

If agent-switch claude reports that the local upstream is not reachable, Claude Code is configured to use a local router such as CC Switch, but that service is not listening on the configured port.

Check the configured base URL in Claude Code settings or the environment:

ANTHROPIC_BASE_URL

For CC Switch, start or restart CC Switch and verify that its local port is healthy. If the router moved to another port, update Claude Code settings or run with an explicit upstream:

agent-switch claude --upstream http://127.0.0.1:

Inspect Conversations

Use the agent-switch dashboard and exports:

agent-switch dashboard
agent-switch webui
agent-switch export / --format md
agent-switch export / --format raw

Load references/agent-switch-capabilities.md when the user asks for the full provider list, storage behavior, export formats, proxy-only mode, or migration/removal commands.

Hermes Local API

When the user asks to call Hermes, treat Hermes as a local API service, not as a CLI. The default base URL is:

http://127.0.0.1:8642

First check health:

GET http://127.0.0.1:8642/health

If Hermes returns 401 for model or chat endpoints and no saved Hermes auth config exists, stop and ask the user for the required Authorization value or token. Do not guess a token and do not silently reuse unrelated OpenAI or Anthropic credentials.

After the user provides the Hermes auth config, save it locally for future calls in:

~/.agent-switch/hermes.json

Use this JSON shape:

{
  "baseUrl": "http://127.0.0.1:8642",
  "authHeader": "Authorization",
  "authValue": "Bearer "
}

Create ~/.agent-switch if needed and restrict file permissions when the platform supports it. Treat this file as sensitive local data. On later Hermes calls, read this config first; only ask again if the file is missing, invalid, or Hermes still returns 401.

Load references/hermes-local-api.md when the user asks for Hermes setup, auth storage, or local API calling behavior.

Code Layout

• code/agent-switch-core: internal capture engine, provider wrappers, store, dashboard, exports, MCP server, and tests.
• code/agent-switch: user-facing CLI entrypoint that invokes the internal engine and prints the Codex handoff.
• cli/agent-switch-skill-.tgz: bundled cross-platform npm CLI package with runtime dependencies.
• scripts/install-agent-switch.js: deterministic local installer for the skill command.

Treat captured logs as sensitive. agent-switch fully masks common authorization, API key, and cookie headers by default, but prompts, tool outputs, request bodies, file paths, and source snippets may still be stored.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ASunYC
• Source: ASunYC/agent-switch-skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.