agentswap

Keep coding when an AI subscription runs out, a provider becomes flaky, or
you need to continue in a different coding-agent harness.

Why agentswap exists

A coding-agent subscription can be expensive and still run out in the middle
of a long refactor. A second subscription may also reach its weekly limit, and
pay-as-you-go API usage can cost much more than the subscription.

Third-party providers such as Krill AI can be a useful lower-cost fallback,
but any provider can be intermittent. When a request fails, repeatedly typing
continue is a poor way to recover the context you already built.

There is another common dead end: Claude Code has no usable capacity, while
Codex still has credits (or the other way around). Starting over in the other
harness throws away the session history.

agentswap is built for these moments. It keeps your credentials local, makes
recovery explicit, and preserves the recorded conversation when you move.

Three ways it keeps work moving

agentswap never changes harnesses silently. You decide when a session should
move from Claude Code to Codex, from Codex to Claude Code, or to another
supported harness.

Install

Homebrew on macOS or Linux

Homebrew installs the checksum-pinned formula from this repository's tap:

brew tap bojieli/agentswap https://github.com/bojieli/agentswap.git
brew install bojieli/agentswap/agentswap

Apple Silicon, Intel, and Linux architectures select their matching archive
automatically. The tap is the same public repository, so no separate account
or package service is required. See the release guide for
how the formula is generated and published.

Go toolchain

go install github.com/bojieli/agentswap/cmd/agentswap@latest

Verified binary installer

The installer downloads the archive and verifies its SHA-256 checksum before
placing the binary in a user-writable directory:

curl -fsSL https://raw.githubusercontent.com/bojieli/agentswap/main/install.sh | sh

For a private repository, GitHub does not serve release assets anonymously.
Use authenticated downloads or wait until the repository and its releases
are public.

Five-minute setup

1. Make sure you are signed in to the CLIs you want to use.

2. Preview what agentswap can discover:

   agentswap import --dry-run
   

3. Import the credentials and active provider settings:

   agentswap import
   

4. Point Claude Code and Codex at the local proxy:

   agentswap install
   

5. Keep the daemon running in the background:

   agentswap service install
   

6. Check the wiring and the account pool:

   agentswap doctor
   agentswap list
   

The existing CLIs continue to be invoked normally:

claude
codex

Run agentswap serve in a terminal when you want to watch the proxy instead
of installing a per-user service.

Import subscriptions and provider fallbacks

agentswap import reads the credentials already stored by Claude Code and
Codex. It does not create a new OAuth flow and it never guesses at an
environment variable that you did not explicitly add.

When a CLI has an active provider override, agentswap imports both sides as
separate entries:

• the native subscription login; and
• the configured Anthropic-compatible or OpenAI-compatible provider, including
  its base URL and authentication style.

That means a setup containing a native Claude subscription and a Krill AI
provider is represented as two choices, rather than one replacing the other.
The same rule applies to Codex and any other provider that speaks the lane's
protocol.

Preview and import safely:

agentswap import --dry-run
agentswap import
agentswap status

Add another signed-in account by logging in through its own CLI, then running:

agentswap login --id work

For a provider key or a long-lived Claude token, use a prompt or stdin so the
secret does not land in shell history:

agentswap add-key anthropic --id krill --base-url https://provider.example
agentswap add-token anthropic

The complete account and provider guide is docs/accounts.md.

Choose your recovery path

Keep the current harness running

agentswap run supervises a CLI. It lets the proxy park a request while a
quota window resets, then resumes the native session if the wait outlives the
client's normal socket timeout:

agentswap run -- claude "refactor the parser"
agentswap run -- codex exec "fix the failing tests"

The first command is still a Claude Code session and the second is still a
Codex session. The supervisor does not change models or provider profiles.

Continue in another harness

Use this when the current provider is unavailable but another harness still
has capacity. For example, if Claude Code has exhausted both subscriptions
and its provider fallback, continue in Codex without starting from a blank
prompt:

agentswap handoff claude codex

handoff validates the newest session in the current directory, creates a
native Codex session, and immediately launches codex resume <id>.

Use teleport when you want to create the target session but inspect or launch
it yourself:

agentswap teleport claude codex
agentswap teleport claude opencode --dry-run

The source and target are always positional and always mean source →
target. You can select an exact source session or directory:

agentswap handoff kimi claude --session <source-id>
agentswap teleport codex opencode --cwd ~/src/project

Harnesses do not share a context window, so a session one held comfortably can
be more than the target can load. agentswap says so before you find out the
hard way, and --compact abridges the thread until it fits:

agentswap handoff claude codex --compact
agentswap teleport claude codex --compact --budget 80k

The reduction is mechanical — no model is asked to summarize anything — and
everything it removes is written to a plain-text archive under
<project>/.agentswap/, with an inline marker at each elision naming the exact
file. It goes in the project because that is where a coding agent is allowed to
read, and it carries a .gitignore so it never becomes a commit.

See the user guide in docs/sessions.md and the exact flag
reference in docs/commands.md.

What transfers, and what does not

Teleportation preserves the recorded conversation rather than reducing it to
a summary prompt. It carries messages, reasoning that the source records,
tool calls and results, call ids, plans, timestamps, model metadata, and
supported inline media.

It deliberately does not move credentials, provider KV caches, hidden or
encrypted runtime state, approvals, live shell processes, background tasks,
or in-memory plugin state. The target is a new native process with its own
permissions and provider configuration.

The source is read-only. Validation happens before the target is written, and
unsupported conversation-bearing records fail closed. OpenCode sessions are
read and written through OpenCode's own export and import commands.

Supported source and target harnesses are:

Reliability boundaries

agentswap distinguishes failures that look similar to a client:

When every account is spent, the default behavior is to park the request for
up to 30 minutes. After that, agentswap returns a 503 with Retry-After and
writes the ticket used by agentswap run.

Security and privacy

agentswap holds live OAuth tokens, so it has no third-party Go dependencies.
The proxy listens on loopback by default, checks the Host header, substitutes
credentials from the pool instead of forwarding the client's credential, and
writes sensitive files with private permissions and atomic replacement.

Session files can contain source code, prompts, and tool output. Treat both
source and target session stores as sensitive local data.

Read the full security model before exposing the daemon or
using a third-party base URL.

Terms of service

agentswap is failover-only: exactly one account is in flight at a time, and
rotation occurs only when the current account is genuinely unavailable. It is
not a parallel throughput multiplier.

Using multiple subscriptions or a third-party provider may still be governed
by that provider's terms. You are responsible for deciding whether your use is
allowed; agentswap is not legal advice.

Limitations

• A stream that fails after partial output cannot be transparently retried.
• Codex learns some quota information from a rejected stream rather than
  successful response headers.
• Automatic wait-and-resume requires agentswap run; a bare CLI receives the
  proxy's error when its request cannot be held any longer.
• Imported OAuth credentials are copies of the CLI's current session. Use a
  long-lived token or an API key for an account that agentswap should own.
• OpenCode must be installed for OpenCode discovery or a non-dry-run target.
• Teleportation cannot move hidden provider state, active processes,
  credentials, approvals, or unsupported media.

See docs/troubleshooting.md when a command does not
behave as expected.

Scope and prior art

Several projects rotate coding-agent accounts. agentswap focuses on the gaps
around rotation: waiting through a reset, preserving a warm conversation,
resuming after a long hold, and moving a structured session between harnesses.

If you only need account rotation, compare projects such as
CC-Router,
claude-swap,
teamclaude,
llmux, and
coding_agent_account_manager.
The scope here stays deliberately narrow: one account in flight, no live
protocol translation, and no third-party dependencies.

Contributing

Bug fixes, clearer documentation, tests, and adapters for additional coding
agents are welcome. A useful contribution usually starts with a reproducible
failure and a test that describes the behavior before the fix.

The project deliberately has no third-party Go dependencies because it holds
live credentials. Read CONTRIBUTING.md before adding a
provider lane, a session adapter, or a dependency.

Please report credential leaks and other security vulnerabilities privately via
the process in SECURITY.md, never in a public issue.

Documentation map

• Getting started and documentation index
• Accounts, subscriptions, keys, and provider overrides
• Session recovery, teleport, and handoff
• Complete command reference
• Configuration
• Troubleshooting
• Architecture and adding a lane
• Acceptance and compatibility evidence
• Live teleport acceptance
• Releases and Homebrew publishing
• Contributing
• Security
• Code of conduct
• Changelog

Project status

The core proxy, importer, supervisor, and session adapters are covered by unit
and end-to-end tests. Compatibility with real provider and harness versions is
recorded in the acceptance documents, but this is still early software: test
it with a disposable account pool before relying on it for unattended work.

License

MIT