Run Claude Code subagents on non-Claude models. A subagent whose model is a
configured id (say deepseek/deepseek-v4-flash) is launched with the ordinary Agent
tool and gets everything a native subagent gets: Claude Code's system prompt,
CLAUDE.md, every tool with its schema, deferred MCP tools, skills, reminders and
compaction. Only the model answering it changes.
Two parts: a mod (a Claude Code plugin) that routes requests for configured ids, and a gateway (a small Bun daemon) that serves them from any OpenAI- or Anthropic-compatible API, with retries and fallback chains.
Needs mise and Claude Code. Works on Linux and macOS.
mise use -g bun github:execution-associates/subagent-models
subagent-models install # config, background service, started
$EDITOR ~/.config/subagent-models/config.yml
subagent-models check # validate; prints models, chains and agentsThen load the mod in Claude Code, in ~/.claude/settings.json:
{ "env": { "CLAUDE_CODE_PLUGIN_DIRS": "~/.local/share/subagent-models/app/mod" } }and call an agent from your config: Agent(subagent_type: "subagent-models:<name>", …).
Private repo, upgrades, and installing from a checkout
- Private repo: mise needs a GitHub token that can read it, in
GITHUB_TOKENorMISE_GITHUB_TOKEN. - Upgrade:
mise upgrade github:execution-associates/subagent-models, thensubagent-models installagain.installis idempotent: it re-points~/.local/share/subagent-models/appat the new version, rewrites the service files and restarts the gateway. It never overwrites an existing config. - From a checkout:
bin/subagent-models installlinks the checkout instead, so the service and the mod run your working tree. - One session only:
claude --plugin-dir ~/.local/share/subagent-models/app/mod. - Remove:
subagent-models uninstallstops and removes the service and the link. Config and state stay.
subagent-models install registers the gateway as a per-user background service that
starts at login and restarts if it dies. The same commands work on both systems:
subagent-models status # service state, then the gateway's chains, cooldowns, last 20 requests
subagent-models logs -f # one line per request: agent, model -> served by, status, ttfb, usage
subagent-models restart # only needed when gateway.socket changes; config edits apply live
subagent-models start | stop| Linux | macOS | |
|---|---|---|
| Service | systemd user unit subagent-models.service in ~/.config/systemd/user/ |
launchd agent subagent-models.gateway in ~/Library/LaunchAgents/ |
| Logs | journalctl --user -u subagent-models |
~/Library/Logs/subagent-models/gateway.log |
| Socket | $XDG_RUNTIME_DIR/subagent-models/gateway.sock |
~/.local/state/subagent-models/gateway.sock |
The gateway listens only on that Unix socket (mode 0600), never on a TCP port.
subagent-models serve runs it in the foreground instead. Full request records,
including every attempt, are in ~/.local/state/subagent-models/access.jsonl.
One file: ~/.config/subagent-models/config.yml ($SUBAGENT_MODELS_CONFIG overrides it
for both parts). config.example.yml is the annotated reference,
and install starts you with a copy. Edits are picked up within ~3 s. A broken edit is
reported in the logs and in the Claude Code transcript, and the last good config stays
in force. Errors name the key path:
retry.fallbackChains.acme/big-model[0]: acme/nope: no such model (configured: …).
Add a provider
providers:
acme:
api: openai-completions # POST {baseUrl}/chat/completions
baseUrl: https://api.example.com/v1
apiKey: ACME_API_KEY # env var name, op://Vault/item/field, or "!command"
compat: { maxTokensField: max_completion_tokens }
models:
big-model: { name: Big Model, input: [text, image], contextWindow: 262144, maxTokens: 65536, defaultLevel: high }Every model is addressed as <provider>/<model key>, here acme/big-model.
api: anthropic-messagesposts to{baseUrl}/v1/messages. Its compat knobs:authHeader(x-api-key|bearer),thinkingMode(budget|adaptive|none),thinkingBudgets,stripCacheControl,supportsMidConversationSystem,extraBody.- OpenAI compat knobs (provider level, overridable per model):
reasoningEffortMap(level → value,null= send none),supportsReasoningEffort,maxTokensField,reasoningContentField(reasoning_content|reasoning),replayReasoning(tool-calls|all|none),supportsMultipleSystemMessages,supportsUsageInStreaming,supportsToolChoice,extraBody. - Model fields:
name,upstreamId(defaults to the key),reasoning,input,contextWindow,maxTokens,defaultLevel,compat,timeouts. api: openai-responsesis reserved. The seam isgateway/src/upstream.ts(an adapter is an async generator yielding Anthropic events) plusadapterForingateway/src/chain.ts.
Keys
apiKey is one of:
- the name of an environment variable;
op://Vault/item/field, read withop read(the service-account token comes fromsecrets.opServiceAccountTokenFile);!shell command, whose trimmed stdout is the key.
A literal key is refused. Keys live in the gateway's memory for
secrets.keyCacheSeconds and are fetched again at once after a 401/403. They are never
logged, and error text is scrubbed of known keys. subagent-models key-check acme
resolves one and prints only its length.
Add an agent
agents:
reviewer:
model: acme/big-model:high
description: Reviews a diff for bugs. Give it the diff or a path.
# optional; any agent-definition field passes through:
# prompt: | # default: the general-purpose agent's prompt
# tools: [Read, Bash] # default: every tool
# disallowedTools, maxTurns, skills, mcpServers, permissionMode, memory, initialPrompt, autoCompactWindowIt is registered as subagent-models:reviewer. A plain ~/.claude/agents/*.md (or
project .claude/agents/*.md) whose model: is a configured id works too: routing is
by the id in the request.
Levels. A suffix :off :minimal :low :medium :high :xhigh :max sets the reasoning
level. On an agent it becomes the agent's effort (Claude Code's scale starts at
low, so off and minimal run as low). On a chain entry it is used as written.
Otherwise the request's effort applies, else the model's defaultLevel.
Reserved names. Ids may not contain a Claude model name (claude-…), and the
provider name anthropic is reserved, so a routed id never collides with a real one.
Add a fallback
retry:
fallbackChains:
acme/big-model:
- acme/small-model:high
- anthropic/claude-sonnet-5-5:medium # a real Claude model, on the session's own loginSee fallback semantics for exactly when the chain is walked.
With an omp: block, the gateway uses omp's model registry, logins
and transport, so anything omp can call is a subagent model, with no model list to keep:
omp:
dir: ~/.omp/agent # omp's agent directory (default)
# providers: [deepseek] # optional restriction (default: every omp provider but anthropic)
fallbackChains: true # import omp's retry.fallbackChains, maxRetries, rateLimitWalksChain
agents: [] # omp agents/<name>.md to expose, by name
versionCheck: warn # warn (default) | exact: refuse omp models while omp and its SDK differmacOS: the omp SDK sync installs packages inside an isb sandbox, so it is set up only where
isbis on PATH. Without it, omp-native mode has no SDK to load.
What it uses from omp
- Catalogue: omp's built-in providers,
models.yml, and discovered models. Every<provider>/<model>omp resolves routes here, e.g.deepseek/deepseek-v4-flash.subagent-models omp-find provider/modelshows how one resolves. - Auth: omp's auth store (
agent.db): API keys,!commandkeys, and OAuth logins with refresh, shared safely with running omp sessions. The gateway never holds these keys in its own config. - Transport: omp's
streamSimple, so every API family omp speaks (OpenAI completions and Responses, Anthropic-compatible, Google, Bedrock, …). omp makes one HTTP attempt per call; the gateway's retries, timeouts, cooldowns and chains apply on top. anthropic/…stays the Claude hand-back on the Claude Code session's own login. omp's Anthropic credentials are never used, and the main session is never routed.- Your file wins. A provider under
providers:shadows omp's provider of the same name; a chain, agent or retry setting defined here replaces omp's. Timeouts are always ours.checklabels everything[ours],[omp]or[ours over omp]. - Only omp's
config.yml(chains) and the opted-inagents/<name>.mdare read as files. omp agent prompts are written for omp's tools, so read one before exposing it. Unresolvable chain entries and agents pinned to Claude are skipped with a warning. - Subscription logins (ChatGPT via
openai-codex, a Claude subscription) route like any other provider;checkflags them. Keep them out withproviders:.
Keeping omp's SDK in step with omp
omp updates itself, so the gateway keeps its own copy of omp's SDK
(@oh-my-pi/pi-coding-agent, @oh-my-pi/pi-ai) at the installed omp's version, with
no manual step.
- Where:
~/.local/share/subagent-models/omp-sdk/, one directory per version (about 470 MB each, two kept), withcurrent/previouslinks andstate.json.gateway/omp-sdk/in git is the baseline (18.20.0), reused as the lockfile when the versions match. - Installed omp version: read from the binary without running it (
/usr/local/bin/omp, or$SUBAGENT_MODELS_OMP_BIN), else~/.omp/agent/last-changelog-version. - Sync: checks both packages are on the official registry, installs exactly that
version in a throwaway isb sandbox (
bun install --exact --ignore-scripts), checks the lockfile integrity against the registry, verifies on the host in a separate process (loads, opens the auth store, lists models), then switchescurrentatomically. - Triggers: a change to the omp binary or its changelog marker, the gateway itself
on a mismatch, and a 10-minute retry timer (
subagent-models-omp-sync.{path,timer}on Linux, thesubagent-models.omp-syncagent on macOS). - Failure is never an outage.
currentstays,state.jsonrecords why, retries back off from 1 minute to 1 hour. While versions differ the gateway keeps serving with the SDK it has and logs one warning per reload. - Switching loads the new copy beside the old one; requests in flight finish on the old one. If the new copy fails to load, the old one stays.
subagent-models omp-sdk status # installed omp, SDK in use, sync phase, last error
subagent-models omp-sdk sync --force # sync now, ignoring the backoff
subagent-models omp-sdk rollback # back to `previous`, pinned until omp changes again
subagent-models omp-sdk unpin # follow the installed omp again
subagent-models omp-sdk use 18.19.0 # switch to a verified version on disk
subagent-models logs syncClaude Code ──http.fetch──▶ mod
│ │ body "model" is a configured id?
│ ├─ no → request goes on to Anthropic untouched
│ └─ yes → same request, URL → Unix socket, credentials stripped
│ ▼
│ gateway (Bun)
│ normalize → fallback chain → upstream adapter
│◀──── Anthropic SSE stream ────────────┘
│
└─ chain reaches a Claude model → gateway answers 409 + x-subagent-models-claude-fallback
→ mod re-sends the ORIGINAL request to Anthropic with that model,
on the session's own login (the gateway never holds a Claude credential)
The mod registers the config's agents at session start and re-reads the file when it changes. It validates the YAML with the gateway's own code, so both agree.
What the gateway changes in the request
From gateway/src/canonical.ts:
| Engine sends | Gateway |
|---|---|
x-anthropic-billing-header system block |
dropped (it changes every prompt and would defeat prefix caching) |
"You are powered by the model <id>." |
the serving model's real name, id and provider |
"You are a Claude agent, built on Anthropic's Claude Agent SDK." |
"You are an agent running in Claude Code, Anthropic's agent harness." |
role: "system" messages mid-conversation |
<system-reminder> text in the next user turn, or a system message where the upstream supports it |
tool_addition blocks |
added to the upstream tool list |
tools with defer_loading |
sent only once a ToolSearch result names them |
| server tools (web search, advisor) | dropped (they run on Anthropic's side) |
thread (message-threads beta) |
refused, so Claude Code resends turns whole for that model |
thinking, output_config.effort |
a level, mapped per model |
context_management, diagnostics, metadata, cache_control, … |
dropped for OpenAI upstreams; cache_control kept for Anthropic-compatible ones unless stripCacheControl |
| thinking blocks | signed smg1.… so they replay only to the model that wrote them |
| images in tool results / user turns | OpenAI: moved to a following user turn; text-only models get a note |
| tool names OpenAI refuses | mapped to safe names and back |
/v1/messages/count_tokens |
estimated locally (characters / 3.6) |
stream: false |
streamed upstream, aggregated |
Responses become a normal Anthropic event stream with stop reasons and usage mapped
(cached tokens reported as cache_read_input_tokens). A stream that ends early is an
error, never a short answer. ping events go out every pingIntervalSeconds while
the upstream is quiet.
Fallback semantics
Vocabulary follows omp (retry.maxRetries, retry.rateLimitWalksChain,
retry.fallbackChains, streamFirstEventTimeoutSeconds, streamIdleTimeoutSeconds).
- A request's chain is
[its model, ...fallbackChains[its model]]. - Each model gets
1 + maxRetriesattempts (backoffbaseDelayMs·2^n, capped atmaxDelayMs) on connection errors, 5xx/529/408, first-event timeout, an unfinished stream, and 429 whenrateLimitWalksChain: false. A 429 withrateLimitWalksChain: true, 401/403 (after one fresh key fetch) and 404 walk on at once. - Walking away from a model cools it down for
cooldownSeconds(a 429'sretry-afterwins). If every model is cooling, all are tried anyway. A success clears the cooldown. - A context-length refusal comes back as Anthropic's
prompt is too long, so Claude Code compacts. Other 400/422s are returned, not walked past (walkOnClientErrors: truechanges that). - The switch happens only before the first event reaches Claude Code. After that,
a stall (
streamIdleTimeoutSeconds) or error aborts the call, cools the model, and sendsoverloaded_error; Claude Code retries and the retry walks past it. - Claude entries (
anthropic/<model>[:level]) are handed back to the mod, which only accepts a Claude model its own copy of the config names in that chain. - Every gateway error carries
x-should-retry: false(it already retried) and names every attempt.
Fail closed
Nothing meant for another model is ever answered by Claude by accident.
- Mod not loaded: the id reaches Anthropic and fails
model_not_found. - Gateway down: the mod answers 503 naming the socket and
subagent-models status. - The routing hook itself fails: 503 for a configured id.
- A Claude hand-back the chain does not name is refused.
- No config at session start: the last good config keeps routing its ids, so they still fail loudly.
Debugging, context windows, known gaps
Debugging. Set gateway.captureDir to dump each engine request and each translated
upstream body (conversation text: turn it off afterwards). claude --debug shows the
mod's [subagent-models] lines and autocompact: … effectiveWindow=.
Context window. Claude Code assumes a 1M window for an id it does not know.
autoCompactWindow can only lower that, so the mod sets it on config agents whose
contextWindow is under 1M (minimum 100K). A .md agent on a smaller model should set
autoCompactWindow itself.
Known gaps.
- Dollar costs are placeholders (
costBasis: "unknown"); token counts are right. Tokens of a Claude fallback are booked under the routed id. -pruns print[claude-code:unrecognized_model]once on stderr.- The first request per model per session costs one local round trip (the thread
refusal), which
--debuglogs as an API error. count_tokensis an estimate. PDFs are replaced with a note; text documents are inlined.- Server tools (Anthropic-side web search, advisor) are unavailable to routed agents.
- An agent removed from the config stays registered (hidden) until the mod reloads.
- The gateway's own adapters lack
openai-responses(omp-native mode reaches it). - Through omp's transport, tool-call arguments arrive whole rather than streamed.
- The default agent prompt is a copy of the general-purpose agent's and can drift.
Tests and releases
Run tests in a sandbox with only gateway/ and mod/ mounted:
bun test # gateway: translation goldens, config, chains, service files
claude plugin test mod # mod: routing, Claude hand-back, registration
claude plugin validate mod
tsc -p modRelease: bump version in mod/.claude-plugin/plugin.json, then push a matching
tag (v0.2.0). The release workflow attaches the source archive that mise use -g github:execution-associates/subagent-models installs.