convez.ai
SkillAutomaçãoAvançado
ASunYC

Agent Switch Skill

ASunYC/agent-switch-skill

Delegar trabalho entre agentes com captura de conversas e logs

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill que permite agentes de código (como Codex e Claude Code) delegarem tarefas a outros agentes CLI enquanto captura conversas de modelo, chamadas de ferramentas e logs. Inclui dashboard local, exportação de conversas e resumos de handoff automáticos.

Instalação

$npx convez-ai ASunYC/agent-switch-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Delegação de tarefas entre múltiplos agentes de IA
  • Captura e auditoria de requisições de modelo e respostas
  • Análise de comportamento de diferentes agentes CLI
  • Isolamento de contas locais com profiles nomeados
  • Exportação de conversas em múltiplos formatos (JSON, HAR, Markdown)

Veredito

Ferramenta técnica voltada para desenvolvedores que usam múltiplos agentes de código. A captura de conversas e handoff automático são úteis para debug e orquestração, mas requer familiaridade com CLI e infraestrutura local.

README

A tradução para o português deste README ainda está na fila.

Agent Switch Skill

A Codex-ready skill and bundled CLI for switching coding agents, capturing model conversations, and returning clean handoff summaries.

Author: ASunYC


Overview

Agent Switch Skill packages the agent-switch command as an installable agent skill. It lets Codex, Claude Code, CodeWhale, OpenCode, and other coding agents delegate work to another CLI while recording the model API traffic that passes through the local capture proxy.

It helps you:

  • Install a ready-to-use agent-switch CLI from the skill directory
  • Start another coding CLI with one command, such as agent-switch claude
  • Capture prompts, tool calls, responses, status codes, and request metadata
  • Open a local dashboard over saved agent conversations only when requested
  • Export captured requests as Markdown, raw HTTP, JSON, or HAR
  • Return a concise handoff summary back to the current Codex session
  • Run proxy-only mode for IDEs or custom OpenAI/Anthropic-compatible clients
  • Isolate multiple local CLI accounts with named profiles
  • Remember local Hermes API authorization after asking the user once

Design Goals

Agent Switch Skill is designed to be simple for agents to bootstrap automatically:

  • Node.js 18+ runtime
  • Skill-first installation flow for Codex
  • Bundled CLI package under cli/
  • One-command agent switching
  • Local-only capture storage
  • Provider recipes for common coding CLIs and model gateways
  • Clear handoff output after delegated work finishes

Agent Skill Flow

When a user says "use agent-switch-skill" or asks Codex to switch agents, Codex should first verify that the CLI is installed:

agent-switch --help

If the command is missing, run the bundled installer from this skill directory:

node scripts/install-agent-switch.js

The installer installs the bundled CLI package from cli/, verifies agent-switch --help, and prints diagnostic output if installation or PATH verification fails.

Features

Core Capabilities

  • Agent handoff: run another coding CLI and return to Codex when it exits
  • Conversation capture: inspect model-facing requests and responses
  • Dashboard: browse saved logs in a local web UI
  • Exports: write captured requests as raw, md, json, or har
  • Provider wrappers: support Claude Code, Codex, CodeWhale, DeepSeek-TUI legacy shims, Kimi, OpenCode, and compatible gateways
  • CLI profiles: isolate Claude Code, Codex, and OpenCode accounts/configs under ~/.agent-switch/profiles
  • Custom commands: wrap arbitrary CLIs with agent-switch run --provider <provider> -- <cmd...>
  • Storage migration: move legacy project logs into the global store
  • Session cleanup: delete sessions and reclaim orphaned content blobs

Technical Highlights

  • Skill-bundled source code under code/
  • No separate package download is required for local development
  • Global command installed from the current checkout
  • Redacts auth headers by default
  • Uses content-addressed storage for captured payloads
  • Includes Node test coverage for CLI, providers, parsing, storage, exports, and handoff behavior

Installation

Option 1: Ask Codex to Install It

Copy this prompt into Codex:

Please install Agent Switch Skill:

1. Clone the repository:
   git clone https://github.com/ASunYC/agent-switch-skill.git

2. Install it into the Codex skills directory:
   Copy-Item -Recurse agent-switch-skill $env:USERPROFILE/.codex/skills/agent-switch-skill

3. Enter the installed skill directory and install the CLI:
   cd $env:USERPROFILE/.codex/skills/agent-switch-skill
   node scripts/install-agent-switch.js

4. Verify the command:
   agent-switch --help

After installation, tell me how to run `agent-switch claude` and inspect captured conversations.

Option 2: Manual Installation

Clone the repository:

git clone https://github.com/ASunYC/agent-switch-skill.git
cd agent-switch-skill

Install it into your Codex skill directory:

# Windows PowerShell
Copy-Item -Recurse . $env:USERPROFILE/.codex/skills/agent-switch-skill
# macOS / Linux
mkdir -p ~/.codex/skills
cp -R . ~/.codex/skills/agent-switch-skill

Install the global CLI:

node scripts/install-agent-switch.js

Verify the installation:

agent-switch --help

Option 3: Build the Bundled CLI Package

Build the npm tarball that ships with the skill and includes runtime dependencies:

npm run build:package

The package is written to cli/ and can be installed on any machine with Node.js 18 or newer:

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

This is the release shape used by scripts/install-agent-switch.js, so a cloned skill repository can install the CLI without relying on the skill directory to already contain node_modules.

Usage

Quick Start

# Pick a CLI from a searchable terminal picker
agent-switch

# Start Claude Code through agent-switch
agent-switch claude

# Start Codex through agent-switch
agent-switch codex

# Start CodeWhale through agent-switch
agent-switch codewhale

# Start DeepSeek-TUI legacy shim through agent-switch
agent-switch deepseek

# Start Claude Code against Kimi / Moonshot
agent-switch kimi

# Open the saved-log dashboard
agent-switch dashboard
agent-switch webui

Run Another CLI

Pass normal CLI arguments after the provider name:

agent-switch claude --resume
agent-switch codex --model gpt-5
agent-switch codewhale
agent-switch opencode

Wrap a custom command:

agent-switch run --provider openai -- my-openai-compatible-cli
agent-switch run --provider claude -- my-anthropic-compatible-cli
agent-switch run --upstream https://my.api/v1 --env-var MY_BASE_URL -- my-tool

Captured CLI runs do not open a browser by default. When the delegated CLI exits, Agent Switch prints a Codex handoff summary with the exit code, session id, captured request count, dashboard command, and latest export command.

Running agent-switch without a command opens a searchable terminal picker for supported CLIs. Explicit commands such as agent-switch codex still start directly without prompting.

Multiple CLI Accounts

Profiles isolate a target CLI's account/config directory while keeping the current project directory unchanged.

For Codex, use one command:

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

When --profile is present, Agent Switch opens a searchable local Codex auth picker:

Select Codex auth

Type to search saved auth
> add auth
  saved Codex auth account
  remove auth

Choosing add auth starts the normal codex login flow in a temporary login directory, then saves the resulting auth into the local account store:

~/.agent-switch/profiles/codex/.accounts/

Choosing an existing saved auth injects that account into the requested runtime profile before Codex starts:

~/.agent-switch/profiles/codex/work/auth.json

Then Codex launches in the current project directory with:

CODEX_HOME=~/.agent-switch/profiles/codex/work

This means agent-switch codex --profile work uses the selected Codex account while staying in the current project folder. If the profile already has saved Codex sessions and no extra Codex arguments were supplied, Agent Switch resumes the latest session by default with resume --last. If the profile has no sessions yet, it starts a new Codex session.

To choose a session yourself, 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 <session-id>

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

Plain agent-switch codex is not changed and continues to use the normal default Codex account/config.

Claude Code and OpenCode profiles remain simple isolated config directories:

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

Profile directories are stored under:

~/.agent-switch/profiles/<tool>/<name>

Shared profiles may link or copy safe files such as config.toml, settings.json, skills, commands, and plugins. Agent Switch never shares known auth/session files such as Codex auth.json, Claude .credentials.json, session folders, or history files unless a Codex auth is explicitly selected from the local auth menu.

Treat ~/.agent-switch/profiles/codex/.accounts as sensitive local data because it stores saved Codex auth snapshots for injection.

Headroom Compact

Compact mode is off by default. Normal captured runs stay transparent and forward Claude Code requests unchanged.

Enable compact mode explicitly for 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. Install and start Headroom separately:

pip install "headroom-ai[proxy]"
headroom proxy
agent-switch compact doctor

By default, compact mode is fail-open. If Headroom is unavailable, Agent Switch records the failure and forwards the original Claude request:

agent-switch claude --compact --compact-fail open

Use fail-closed only when you prefer stopping the request over sending uncompressed context:

agent-switch claude --compact --compact-fail closed

The dashboard stores and displays both views: the original request captured from Claude Code and the forwarded request sent upstream after compression. RTK is not initialized by compact v1; command-output compression can be evaluated separately later.

Missing Target CLI

Agent Switch installs the capture command, but it does not silently install third-party coding CLIs. If the delegated CLI is missing, Agent Switch prints targeted install guidance.

For Claude Code, install it first:

# Windows
winget install Anthropic.ClaudeCode

# Windows alternative
irm https://claude.ai/install.ps1 | iex
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# macOS Homebrew
brew install --cask claude-code

Then reopen the terminal and verify:

claude
agent-switch claude

For CodeWhale, install the renamed DeepSeek-TUI package:

npm install -g codewhale
# or
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

Then verify:

codewhale doctor
agent-switch codewhale

Local Upstream Not Reachable

If agent-switch claude says the local upstream is not reachable, Claude Code is pointing at a local router such as CC Switch, but nothing is listening on that port.

For example:

ANTHROPIC_BASE_URL=http://127.0.0.1:15721

Start or restart CC Switch, verify the configured port is healthy, and retry:

agent-switch claude

If the router moved to a different port, pass it explicitly:

agent-switch claude --upstream http://127.0.0.1:<port>

Inspect Conversations

# Open the dashboard over saved logs
agent-switch dashboard
agent-switch webui

# Export one captured request as Markdown
agent-switch export <session>/<seq> --format md

# Export raw HTTP
agent-switch export <session>/<seq> --format raw

# Export machine-readable data
agent-switch export <session>/<seq> --format json
agent-switch export <session>/<seq> --format har

Manage Stored Logs

# Copy legacy ./.agent-switch logs from the current project into the global store
agent-switch migrate

# Repack stored captures into the deduped storage format
agent-switch repack

# Repack one session
agent-switch repack <session>

# Delete a session and reclaim orphaned blobs
agent-switch rm <session>

Commands

Basic Commands

CommandExampleDescription
claudeagent-switch claudeStart Claude Code with capture enabled
codexagent-switch codexStart Codex with capture enabled
codewhaleagent-switch codewhaleStart CodeWhale with capture enabled
codewhale-tuiagent-switch codewhale-tuiStart the CodeWhale TUI binary directly
deepseekagent-switch deepseekStart the DeepSeek-TUI legacy shim with capture enabled
deepseek-tuiagent-switch deepseek-tuiStart the DeepSeek-TUI legacy runtime shim directly
kimiagent-switch kimiStart Claude Code against Kimi / Moonshot
opencodeagent-switch opencodeStart OpenCode with capture enabled
runagent-switch run --provider openai -- my-cliWrap an arbitrary compatible CLI
dashboardagent-switch dashboardOpen the dashboard over saved logs
webuiagent-switch webuiAlias for dashboard
viewagent-switch viewBackward-compatible alias for dashboard
profileagent-switch profile new claude/workManage isolated CLI account/config profiles
installagent-switch installPrint local install and update commands

Log and Proxy Commands

CommandExampleDescription
exportagent-switch export <id> --format mdExport a captured request
migrateagent-switch migrateCopy legacy project logs into the global store
repackagent-switch repack <session>Repack stored captures
rmagent-switch rm <session>Delete a saved session
proxyagent-switch proxy --provider openaiRun only the proxy and dashboard

Useful Options

OptionDescription
--provider <name>Force the provider recipe for run or proxy
--upstream <url>Override the upstream model API URL
--base-url <url>Alias for --upstream
--port <n>Set the dashboard port
--proxy-port <n>Set the capture proxy port
--dir <path>Set the log directory
--openOpen the dashboard browser during a captured CLI run
--no-openKeep a dashboard command headless, useful for tests or remote shells
--no-redactSave auth headers without masking them
--no-mcpDo not inject Agent Switch MCP tools into Claude Code
`--profile <nametool/name>`
--env-var <name>Override which environment variable receives the proxy URL

Supported Providers

Built-in provider recipes include:

  • claude
  • codex
  • codex-azure
  • codewhale
  • codewhale-tui
  • deepseek
  • deepseek-tui
  • kimi
  • openai
  • opencode
  • ollama
  • lmstudio
  • openrouter
  • glm
  • bedrock
  • vertex

See references/agent-switch-capabilities.md for provider details, storage behavior, export formats, and proxy-only usage.

Hermes Local API

Hermes is treated as a local Docker-hosted API service, not as a spawned CLI. The default endpoint is:

http://127.0.0.1:8642

When Hermes returns 401 and no saved auth config exists, Agent Switch Skill asks the user for the required Authorization value and stores it locally in:

~/.agent-switch/hermes.json

See references/hermes-local-api.md for the saved config format and call flow.

Project Structure

agent-switch-skill/
|-- README.md                         # Project documentation
|-- SKILL.md                          # Codex skill definition
|-- package.json                      # Global CLI package metadata
|-- agents/
|   `-- openai.yaml                   # Agent metadata
|-- cli/
|   `-- agent-switch-skill-0.1.0.tgz  # Bundled CLI package with runtime dependencies
|-- scripts/
|   |-- build-agent-switch-package.js # Build a dependency-bundled npm package
|   `-- install-agent-switch.js       # One-command CLI installer
|-- references/
|   `-- agent-switch-capabilities.md  # Extended capability map
`-- code/
    |-- agent-switch/                 # User-facing CLI wrapper and handoff output
    `-- agent-switch-core/            # Capture proxy, dashboard, store, exports, and tests

Runtime captures are stored under:

~/.agent-switch/sessions/
|-- <encoded-project-path>-<hash>/
|   `-- <session>/
|       |-- 0001.json
|       `-- ...
`-- blobs/

The dashboard can also read legacy project-local logs from:

./.agent-switch/

Configuration

Node.js

Agent Switch Skill requires Node.js 18 or newer:

node --version

Provider Credentials

Agent Switch forwards requests to the upstream provider already configured for the delegated CLI. Keep using the credentials required by that CLI, such as ANTHROPIC_API_KEY, OPENAI_API_KEY, or provider-specific environment variables.

Capture Privacy

Agent Switch masks auth headers by default. Captured logs may still include prompts, tool outputs, file paths, source snippets, and other sensitive content. Treat ~/.agent-switch as private local data.

FAQ

Why does agent-switch --help fail after installing the skill?

The skill and the CLI are two layers. Installing the skill gives Codex the instructions and bundled CLI package. Installing the CLI adds agent-switch to your global PATH. Run:

node scripts/install-agent-switch.js

If the command still fails in the same terminal, open a new terminal and run:

agent-switch --help

Can I use npx instead of installing globally?

You can run temporary commands with package tooling during development, but the recommended skill flow is to install the bundled CLI package from cli/ so Codex can call agent-switch consistently.

Why is the Codex dashboard empty?

Codex must send model traffic through an OpenAI-compatible base URL for capture. ChatGPT-login WebSocket mode bypasses OPENAI_BASE_URL, so Agent Switch will warn when it detects that mode.

Where do captured conversations go?

New captures are stored under ~/.agent-switch/sessions/<encoded-project-path>-<hash>/. Use agent-switch dashboard to browse them or agent-switch export <id> to export one request.

Can I delete captured data?

Yes. Use:

agent-switch rm <session>

You can also remove the local ~/.agent-switch directory manually if you want to clear all saved captures.

Changelog

v0.1.0

  • Added agent-switch skill packaging
  • Added global CLI installer
  • Added handoff output for Codex
  • Added provider wrappers for common coding CLIs
  • Added dashboard, export, migration, repack, and cleanup commands
  • Added tests for core capture and CLI behavior

Contributing

Contributions are welcome.

You can help by:

  • Improving provider recipes
  • Adding capture formats
  • Improving dashboard inspection workflows
  • Expanding cross-agent handoff behavior
  • Reporting CLI compatibility issues
  • Improving documentation

Please open an issue or pull request on GitHub:

https://github.com/ASunYC/agent-switch-skill/issues

License

MIT License

Copyright (c) 2026 ASunYC


If Agent Switch Skill helps you, a GitHub Star is appreciated.

Made by ASunYC | Powered by Node.js

Ver o original no GitHub

Bom para

Relacionados