Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

subagent-models

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.

Install

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 agents

Then 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_TOKEN or MISE_GITHUB_TOKEN.
  • Upgrade: mise upgrade github:execution-associates/subagent-models, then subagent-models install again. install is idempotent: it re-points ~/.local/share/subagent-models/app at the new version, rewrites the service files and restarts the gateway. It never overwrites an existing config.
  • From a checkout: bin/subagent-models install links 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 uninstall stops and removes the service and the link. Config and state stay.

Run the daemon

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.

Configure

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-messages posts 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-responses is reserved. The seam is gateway/src/upstream.ts (an adapter is an async generator yielding Anthropic events) plus adapterFor in gateway/src/chain.ts.
Keys

apiKey is one of:

  • the name of an environment variable;
  • op://Vault/item/field, read with op read (the service-account token comes from secrets.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, autoCompactWindow

It 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 login

See fallback semantics for exactly when the chain is walked.

omp-native mode

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 differ

macOS: the omp SDK sync installs packages inside an isb sandbox, so it is set up only where isb is 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/model shows how one resolves.
  • Auth: omp's auth store (agent.db): API keys, !command keys, 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. check labels everything [ours], [omp] or [ours over omp].
  • Only omp's config.yml (chains) and the opted-in agents/<name>.md are 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; check flags them. Keep them out with providers:.
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), with current/previous links and state.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 switches current atomically.
  • 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, the subagent-models.omp-sync agent on macOS).
  • Failure is never an outage. current stays, state.json records 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 sync

How it works

Claude 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 + maxRetries attempts (backoff baseDelayMs·2^n, capped at maxDelayMs) on connection errors, 5xx/529/408, first-event timeout, an unfinished stream, and 429 when rateLimitWalksChain: false. A 429 with rateLimitWalksChain: 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's retry-after wins). 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: true changes 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 sends overloaded_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.

Troubleshooting

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.
  • -p runs print [claude-code:unrecognized_model] once on stderr.
  • The first request per model per session costs one local round trip (the thread refusal), which --debug logs as an API error.
  • count_tokens is 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.

Development

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 mod

Release: 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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages