Model Boss

Big models think. Small models ship.

Cross-model coding orchestration for Claude Code and Codex. The conversation's host-selected or inherited main loop is immutable input: Model Boss never replaces it. The Boss is the workflow authority holder—Lite keeps that authority inline in the inherited main loop, while Max uses a distinct, verified authority reviewer. "Big" and "small" are workflow-relative roles, not a universal ranking of providers or models.

Canonical repository: https://github.com/vincemakes/model-boss

Usage

After install (see the Claude Code and Codex setup sections below) there is no command to run — you invoke Model Boss conversationally. Phrases like model boss, save model tokens, or 分层干活 trigger the skill; then describe the topology you want:

use model boss: let sonnet implement the retry logic in src/http, you review   → Lite
走 model boss,让 opus 去开发,你来审核                                           → Lite
model boss max — have fable review the plan and the final diff                → Max
走 model boss max,让 fable 审计划和最终 diff                                     → Max

In Lite the inherited main loop keeps both authority checkpoints and dispatches an optional worker. In Max a distinct, verified reviewer approves the plan before dispatch and the final evidence before integration — and an explicit Max request stops with reviewer_unavailable rather than silently degrading.

Before any work starts, Model Boss prints the resolved topology verdict (Main loop / Resolved mode / Authority / Worker / Resolution source). Read it: worker and reviewer names are route aliases, and the verdict shows the canonical model each alias actually resolved to on your host — for example opus resolves to the newest Opus your host exposes, which on a not-yet-updated host can lag the newest public release. A route name is never identity proof.

Tiny edits, pure discussion, and unresolved root-cause debugging do not justify orchestration: Model Boss steps aside and the main loop works normally.

Should you use it?

Use Model Boss when a task is bounded, constructive, and large enough to repay orchestration overhead: a material multi-file implementation, a migration, repeated mechanical changes, or independent packets with testable acceptance criteria.

Let the main loop work normally for a tiny edit, pure conversation or analysis, unresolved root-cause debugging, or a design/security decision that cannot yet be expressed as acceptance criteria. Rough signals such as 300+ changed lines or 6+ files can help, but task shape matters more than a fixed threshold.

The published measurements are a historical Claude/Fable/Opus snapshot, not a promise for every model profile. See the scoped benchmark report before choosing Model Boss for cost or quota reasons.

Lite and Max at a glance

Lite and Max describe where authority lives. They do not name a provider, price tier, or universal model-quality ranking.

Mode	Authority topology	Worker
Lite	The inherited main loop plans, performs both authority checks, reviews, and integrates.	An optional worker can implement, scout, or perform mechanical work.
Max	A distinct, verified authority reviewer checks the plan and final evidence while the inherited main loop coordinates and reviews.	The worker is optional; Max can have two levels or three.

Lite
authority main loop ── plans / reviews / integrates ──> optional worker

Max
authority reviewer <── plan and final evidence ── inherited main loop
                                                   └── optional worker

Examples are capability mappings, not hard-coded provider rules:

Fable or Opus as the main loop with a lower Claude worker is Lite.
Sol as the main loop with Terra or Luna workers is Lite.
Terra as the main loop with a Sol reviewer and an optional Luna worker is Max.
Kimi K3 can be an authority-capable external route only when its exact model identity is pinned, verified live, read-only, and distinct from the main loop.

A separate worker is never required. Lite may run entirely in the main loop; Max always requires its separate reviewer but may let the main loop implement.

The main loop is already selected

The host-selected conversation model is immutable input. Model Boss never replaces it, and profile, user, project, or per-run configuration must not contain a substitute main loop. If the host cannot establish the main loop's canonical provider_family:resolved_model_id:variant fingerprint, resolution stops with needs_context.

Route names, wrapper names, endpoints, accounts, and model-family prose are hints, not identity proof. Two different aliases that resolve to the same canonical fingerprint are the same model for authority-separation purposes.

How the shared state machine works

Lite and Max use the same ordered state machine:

RESOLVE -> PREFLIGHT -> CLASSIFY -> RECON -> DRAFT_PLAN -> AUTHORITY_PLAN_CHECK -> DISPATCH -> GATE -> PATCH_AUDIT -> MAIN_LOOP_REVIEW -> AUTHORITY_FINAL_CHECK -> INTEGRATE

Lite binds both authority checkpoints to the main loop inline. Max binds both checkpoints to one distinct eligible reviewer. Max cannot dispatch before plan approval, and neither mode can integrate before gates, a complete patch audit, main-loop review, and final approval.

For a sealed external-worker invocation, the chosen topology is also a runtime invariant: the required worker --mode lite|max value is recorded as authority_mode in the sealed bundle. That authority_mode cannot be switched, downgraded, or reinterpreted during review or integration. A Lite bundle accepts only inline main-loop authority; a Max bundle accepts only a distinct external reviewer.

Workers receive a bounded task packet instead of conversation history. They work in a disposable worktree, and their claims are checked against independently captured process and Git evidence. Final approval is bound to exactly:

source_snapshot_hash
worker_delta_hash
projected_task_patch_hash

If any evidence or destination state changes, the old approval cannot be reused. The full state, evidence, retry, and integration contract is in the protocol reference.

Model profiles, not model lock-in

Profiles provide capability-based route defaults:

authority routes may review in Max or keep authority inline in Lite.
balanced routes may coordinate or implement.
fast routes may implement, scout, or perform mechanical work.

Those declarations are candidates, not proof. Preflight must verify live reachability, exact effective identity, permissions, credential names, and—when an external command can write—a sandbox bound to that exact invocation.

Built-in profiles cover Claude, OpenAI, and Kimi examples, while project and user configuration can replace route definitions. Resolution follows profile → user → project → per-run precedence and never mutates the inherited main loop. The published examples and schema are config/model-boss.example.json and config/model-boss.schema.json; project discovery uses .model-boss.json. On POSIX, user discovery uses $XDG_CONFIG_HOME/model-boss/config.json only when XDG_CONFIG_HOME is absolute; otherwise it uses $HOME/.config/model-boss/config.json. On PowerShell, an absolute $env:XDG_CONFIG_HOME wins; otherwise the runtime reads absolute $env:HOME and falls back to absolute $env:USERPROFILE only when HOME is absent. The displayed fallback $HOME\.config\model-boss\config.json uses PowerShell's $HOME convenience variable. Missing or relative selected roots fail closed. See routing and capability resolution for the complete rules.

The runtime CLI requires Python 3.11+ and Git. The POSIX setup examples also use bash and install. A write-capable external worker additionally requires a verified OS backend: /usr/bin/sandbox-exec on macOS or Bubblewrap (bwrap) on Linux, including WSL. Native Windows has no external-writer backend and uses host-native Claude Code or Codex agents instead.

Claude Code setup

These are fresh-install commands. Each scope installs the skill plus the four host-specific role declarations.

POSIX — user scope

mkdir -p "$HOME/.claude/skills"
git clone https://github.com/vincemakes/model-boss.git "$HOME/.claude/skills/model-boss"
mkdir -p "$HOME/.claude/agents"
for role in reviewer implementer mechanic scout; do
  install -m 0644 "$HOME/.claude/skills/model-boss/assets/agents/claude-code/$role.md" \
    "$HOME/.claude/agents/model-boss-$role.md"
done

POSIX — project scope

mkdir -p .claude/skills
git clone https://github.com/vincemakes/model-boss.git .claude/skills/model-boss
mkdir -p .claude/agents
for role in reviewer implementer mechanic scout; do
  install -m 0644 ".claude/skills/model-boss/assets/agents/claude-code/$role.md" \
    ".claude/agents/model-boss-$role.md"
done

PowerShell — user scope

$skill = Join-Path $HOME ".claude\skills\model-boss"
$agents = Join-Path $HOME ".claude\agents"
New-Item -ItemType Directory -Force (Split-Path $skill -Parent) | Out-Null
git clone https://github.com/vincemakes/model-boss.git $skill
New-Item -ItemType Directory -Force $agents | Out-Null
foreach ($role in "reviewer", "implementer", "mechanic", "scout") {
  Copy-Item (Join-Path $skill "assets\agents\claude-code\$role.md") `
    (Join-Path $agents "model-boss-$role.md")
}

PowerShell — project scope

$skill = ".claude\skills\model-boss"
$agents = ".claude\agents"
New-Item -ItemType Directory -Force (Split-Path $skill -Parent) | Out-Null
git clone https://github.com/vincemakes/model-boss.git $skill
New-Item -ItemType Directory -Force $agents | Out-Null
foreach ($role in "reviewer", "implementer", "mechanic", "scout") {
  Copy-Item (Join-Path $skill "assets\agents\claude-code\$role.md") `
    (Join-Path $agents "model-boss-$role.md")
}

Codex setup

Check the installed CLI first:

codex --version

codex --version is diagnostic, not a capability proof. Before selecting the bundled profile, Model Boss preflight must confirm that the installed Codex supports custom agents, that the exact Sol/Terra/Luna IDs are available in the current account and model catalog, and that the requested sandbox and reasoning settings are accepted. A failed availability check returns provider_unavailable or reviewer_unavailable. Setup never upgrades the CLI automatically.

The bundled Sol profile treats Sol as an authority route, Terra as a balanced route, and Luna as a fast route. These are fresh-install commands for the skill and four Codex agent declarations.

POSIX — project scope

mkdir -p .agents/skills
git clone https://github.com/vincemakes/model-boss.git .agents/skills/model-boss
mkdir -p .codex/agents
for role in reviewer implementer mechanic scout; do
  install -m 0644 ".agents/skills/model-boss/assets/agents/codex/$role.toml" \
    ".codex/agents/model-boss-$role.toml"
done

POSIX — user scope

mkdir -p "$HOME/.agents/skills"
git clone https://github.com/vincemakes/model-boss.git "$HOME/.agents/skills/model-boss"
mkdir -p "$HOME/.codex/agents"
for role in reviewer implementer mechanic scout; do
  install -m 0644 "$HOME/.agents/skills/model-boss/assets/agents/codex/$role.toml" \
    "$HOME/.codex/agents/model-boss-$role.toml"
done

PowerShell — project scope

$skill = ".agents\skills\model-boss"
$agents = ".codex\agents"
New-Item -ItemType Directory -Force (Split-Path $skill -Parent) | Out-Null
git clone https://github.com/vincemakes/model-boss.git $skill
New-Item -ItemType Directory -Force $agents | Out-Null
foreach ($role in "reviewer", "implementer", "mechanic", "scout") {
  Copy-Item (Join-Path $skill "assets\agents\codex\$role.toml") `
    (Join-Path $agents "model-boss-$role.toml")
}

PowerShell — user scope

$skill = Join-Path $HOME ".agents\skills\model-boss"
$agents = Join-Path $HOME ".codex\agents"
New-Item -ItemType Directory -Force (Split-Path $skill -Parent) | Out-Null
git clone https://github.com/vincemakes/model-boss.git $skill
New-Item -ItemType Directory -Force $agents | Out-Null
foreach ($role in "reviewer", "implementer", "mechanic", "scout") {
  Copy-Item (Join-Path $skill "assets\agents\codex\$role.toml") `
    (Join-Path $agents "model-boss-$role.toml")
}

Kimi and GLM external routes

From the installed checkout, install the compatibility wrappers into an explicit directory:

bash scripts/setup-model-providers.sh --install-path "$HOME/.local/bin"

With only --install-path, setup installs wrappers only. It does not inspect or import the default legacy credential file, even when that file exists, and it never edits shell startup files. Add the directory to PATH yourself if necessary. Wrappers alone do not make Kimi or GLM available: configure a complete direct environment or credentials document and install the trusted provider binary separately.

For direct environment setup, Kimi requires exactly KIMI_BASE_URL + KIMI_AUTH_TOKEN. GLM requires exactly GLM_BASE_URL + GLM_AUTH_TOKEN + GLM_MODEL + GLM_SMALL_FAST_MODEL.

Alternatively, create a strict version 1 JSON document with placeholders replaced locally:

{
  "version": 1,
  "credentials": {
    "GLM_AUTH_TOKEN": "<glm-auth-token>",
    "GLM_BASE_URL": "<glm-base-url>",
    "GLM_MODEL": "<glm-model>",
    "GLM_SMALL_FAST_MODEL": "<glm-small-fast-model>",
    "KIMI_AUTH_TOKEN": "<kimi-auth-token>",
    "KIMI_BASE_URL": "<kimi-base-url>"
  }
}

On POSIX, credentials discovery uses $XDG_CONFIG_HOME/model-boss/credentials.json only when XDG_CONFIG_HOME is absolute, and otherwise $HOME/.config/model-boss/credentials.json. Secure the chosen directory as 0700 and the file as 0600; for the HOME fallback:

chmod 0700 "$HOME/.config/model-boss"
chmod 0600 "$HOME/.config/model-boss/credentials.json"

On PowerShell, an absolute $env:XDG_CONFIG_HOME wins; otherwise the runtime reads absolute $env:HOME and falls back to absolute $env:USERPROFILE only when HOME is absent. The displayed $HOME\.config\model-boss\credentials.json is the normal PowerShell spelling. An absolute MODEL_BOSS_CREDENTIALS overrides discovery. Never put secrets in the repository, .model-boss.json, or config/model-boss.example.json.

The exact wrapper role mapping is:

Route role	Reviewer transport base command	Write command allowed only inside verified OS sandbox
Kimi reviewer candidate	`claude-kimi`	—
Kimi implementer	—	`claude-kimi-bypass -p`
GLM reviewer candidate	`claude-glm`	—
GLM implementer	—	`claude-glm-bypass -p`
GLM fast scout/mechanic	`claude-glm-turbo`	`claude-glm-turbo-bypass -p`

Resolve the directory containing the installed SKILL.md and call it <model-boss-skill-root>. The target repository does not need to contain Model Boss.

The sealed Max workflow has one exact order. Plan and final review must use the same effective reviewer identity/configuration: route, resolved fingerprint, identity-evidence source, and read-only proof. They must also use the same main-loop fingerprint. The profile path itself may differ when it resolves to those same facts:

mkdir -p "$PWD/../model-boss-runs"
python3 <model-boss-skill-root>/scripts/model-boss.py plan-review \
  --repo "$PWD" \
  --temp-parent "$PWD/../model-boss-runs" \
  --task /absolute/path/to/task.json \
  --context /absolute/path/to/plan-context.json \
  --profile /absolute/path/to/profile.json \
  --route <reviewer-route> \
  --main-fingerprint <provider:model:variant>

python3 <model-boss-skill-root>/scripts/model-boss.py worker --manifest <manifest> \
  --repo "$PWD" \
  --temp-parent "$PWD/../model-boss-runs" \
  --route claude-kimi-bypass \
  --task /absolute/path/to/task.json \
  --mode max

python3 <model-boss-skill-root>/scripts/model-boss.py review \
  --profile /absolute/path/to/profile.json \
  --route <same-reviewer-route> \
  --main-fingerprint <same-provider:model:variant> \
  --manifest <manifest> \
  --context /absolute/path/to/review-context.json

python3 <model-boss-skill-root>/scripts/model-boss.py integrate <manifest>

The Max plan context contains exactly version, goal, proposed_plan, acceptance_criteria, and risks. The final context must repeat that approved goal, plan, and criteria, plus its final-only main_loop_verdict. Any task, source, plan, or reviewer change blocks dispatch or approval.

Lite performs plan authority inline. Its external worker creates the invocation and therefore rejects --manifest:

python3 <model-boss-skill-root>/scripts/model-boss.py worker \
  --repo "$PWD" \
  --temp-parent "$PWD/../model-boss-runs" \
  --route claude-kimi-bypass \
  --task /absolute/path/to/task.json \
  --mode lite

python3 <model-boss-skill-root>/scripts/model-boss.py review --inline \
  --main-fingerprint <provider:model:variant> \
  --manifest <manifest> \
  --context /absolute/path/to/review-context.json

python3 <model-boss-skill-root>/scripts/model-boss.py integrate <manifest>

The worker creates a disposable worktree, reruns the sandbox probe, executes the declared gates, and seals the delta without changing the source repository. An approving final review writes an invocation-bound receipt; integration accepts only the manifest and never a caller-supplied approval file.

See the external CLI contract for the exact task and review-context schemas. Do not run a bypass alias directly from an ordinary repository; without the one-shot invocation manifest it fails closed. These same manifest and command contracts can be driven by either a Claude Code or Codex main loop; model/provider names are route data, not branches in the workflow.

Plain wrappers are not inherently read-only. Reviewer transport appends --safe-mode --no-session-persistence --permission-mode plan --tools "" -p, runs from an isolated evidence directory, disables repository and tool access, and verifies that directory did not mutate. Even then, a candidate is ineligible for Max until preflight proves its exact model fingerprint and separation from the main loop.

A command name is not proof of model identity and never establishes independence. Codex can invoke an existing claude-kimi* command as an external route; this does not make Kimi appear natively in the Codex model picker. Wrapper installation never makes Kimi or GLM a native picker entry.

Write-capable bypass routes launch only inside a verified OS sandbox bound to the command, disposable worktree, route state, and sandbox profile. The current verified writer backends are macOS and Linux, including Linux under WSL. Native Windows external writers fail closed with sandbox_unavailable; Claude Code and Codex native-agent orchestration remains available there.

The external worker model receives exactly the Read, Glob, Grep, Edit, and Write tools. Bash is disabled; Web and MCP tools are unavailable. Declared gate commands are direct argument arrays executed by the Model Boss host after the model call, not shell access granted to the model.

Safety and failure behavior

Model Boss fails closed:

An explicit Max request never silently degrades to Lite. An unavailable, colliding, unverified, or effectively write-capable reviewer blocks dispatch.
External writers never run in the user's repository. They receive only named credentials in a minimal child environment and can write only inside an invocation-owned disposable worktree.
Prompts, logs, manifests, and review packets omit credential values, but the provider client process still receives the credentials needed to call its endpoint. Prefer a short-lived, narrowly scoped token with the least permissions the route supports. The tool allowlist and filesystem sandbox are not a network security boundary: a malicious or compromised provider binary can misuse credentials or readable data, and Model Boss cannot prevent that binary from sending them over its permitted provider connection. Install and run only provider binaries you trust.
A worker may self-fix failed gates at most three times. Final authority review allows two revision rounds; a third revise returns review_revise without integration.
Out-of-scope writes return scope_violation. Changed evidence returns approval_stale. Destination drift returns destination_changed and requires a fresh snapshot, audit, main-loop review, and authority approval.
Failures report concise non-secret evidence and preserve user changes. Cleanup removes only invocation-owned resources.

The complete public status set is:

ok
needs_context
gate_failed
provider_unavailable
reviewer_unavailable
timeout
scope_violation
transport_error
review_revise
approval_stale
destination_changed
sandbox_unavailable

Reference benchmark snapshot

The full benchmark report is a historical reference for the 2026 Claude/Fable/Opus stack. It does not predict savings for Sol, Kimi, or future profiles.

In that recorded large constructive run, Lite changed strongest-model output tokens by -42% and used a -34% price-weighted quota proxy; Max changed strongest-model output tokens by -89% and used a -88% quota proxy. Those are different measurements and should not be interchanged. The blind bug-hunt is one observed probe, not general proof, and the report preserves its single-run caveat, raw figures, methodology, and negative results.

When Model Boss steps aside

Model Boss steps aside before dispatch for tiny edits, pure conversation, unresolved debugging, judgment-dense work without testable acceptance criteria, or tasks below the delegation floor. It also stops rather than improvising when identity, reviewer, provider, sandbox, gate, scope, approval, or destination invariants fail.

Stepping aside leaves the inherited main loop in charge. It does not switch models, invent a route, weaken Max, or treat orchestration already spent as a reason to continue unsafely.

Migrating from Token Saver

Migration is explicit and no-overwrite. Normal discovery ignores all former paths and old variables. An explicit --legacy-source is required for any legacy import; the default legacy file is not imported by wrapper-only setup. The only canonical legacy-provider import is:

python3 <model-boss-skill-root>/scripts/model-boss.py setup-providers --legacy-source <absolute-old-providers.env>

That command parses the named legacy $HOME/.claude/fable-token-saver/providers.env-format file as data—never as shell code. scripts/setup-model-providers.sh is only a wrapper around the canonical command. Migration never deletes or edits legacy data.

Old JSON credentials are never auto-copied. Manually copy an old JSON credentials file only after checking its file and directory permissions, or point an absolute MODEL_BOSS_CREDENTIALS override at the existing JSON. Old variables are ignored; the exact rows below are manual migration mappings, not compatibility aliases.

Former surface	Model Boss surface
`https://github.com/vincemakes/token-saver`	`https://github.com/vincemakes/model-boss`
`.claude/skills/token-saver`, `.agents/skills/token-saver`	`.claude/skills/model-boss`, `.agents/skills/model-boss`
`scripts/token-saver-route.py`	`scripts/model-boss.py`
`runtime.token_saver`	`runtime.model_boss`
`.token-saver.json`	`.model-boss.json`
`$XDG_CONFIG_HOME/token-saver/config.json` when `XDG_CONFIG_HOME` is absolute	`$XDG_CONFIG_HOME/model-boss/config.json`
`$HOME/.config/token-saver/config.json` otherwise	`$HOME/.config/model-boss/config.json`
`$HOME\.config\token-saver\config.json` on PowerShell unless `XDG_CONFIG_HOME` is absolute	`$HOME\.config\model-boss\config.json`
`$XDG_CONFIG_HOME/token-saver/credentials.json` when `XDG_CONFIG_HOME` is absolute	`$XDG_CONFIG_HOME/model-boss/credentials.json`
`$HOME/.config/token-saver/credentials.json` otherwise	`$HOME/.config/model-boss/credentials.json`
`$HOME\.config\token-saver\credentials.json` on PowerShell unless `XDG_CONFIG_HOME` is absolute	`$HOME\.config\model-boss\credentials.json`
`TOKEN_SAVER_CREDENTIALS`	`MODEL_BOSS_CREDENTIALS`
`TOKEN_SAVER_INVOCATION_MANIFEST`	`MODEL_BOSS_INVOCATION_MANIFEST`
`TOKEN_SAVER_TRUSTED_GATE_FAILURES`	`MODEL_BOSS_TRUSTED_GATE_FAILURES`
`TOKEN_SAVER_PROVIDER_API_KEY`	`MODEL_BOSS_PROVIDER_API_KEY`
`token-saver-<role>.md`, `token-saver-<role>.toml`	`model-boss-<role>.md`, `model-boss-<role>.toml`
`token-saver-runs`	`model-boss-runs`
`config/token-saver.example.json`, `config/token-saver.schema.json`	`config/model-boss.example.json`, `config/model-boss.schema.json`
`dist/token-saver.skill`	`dist/model-boss.skill`

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.github/workflows		.github/workflows
agents		agents
assets/agents		assets/agents
benchmarks		benchmarks
config		config
dist		dist
docs		docs
evals		evals
media		media
references		references
runtime/model_boss		runtime/model_boss
scripts		scripts
tests		tests
.gitignore		.gitignore
BENCHMARKS.md		BENCHMARKS.md
BENCHMARKS.zh-CN.md		BENCHMARKS.zh-CN.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
SKILL.md		SKILL.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Model Boss

Usage

Should you use it?

Lite and Max at a glance

The main loop is already selected

How the shared state machine works

Model profiles, not model lock-in

Claude Code setup

POSIX — user scope

POSIX — project scope

PowerShell — user scope

PowerShell — project scope

Codex setup

POSIX — project scope

POSIX — user scope

PowerShell — project scope

PowerShell — user scope

Kimi and GLM external routes

Safety and failure behavior

Reference benchmark snapshot

When Model Boss steps aside

Migrating from Token Saver

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Model Boss

Usage

Should you use it?

Lite and Max at a glance

The main loop is already selected

How the shared state machine works

Model profiles, not model lock-in

Claude Code setup

POSIX — user scope

POSIX — project scope

PowerShell — user scope

PowerShell — project scope

Codex setup

POSIX — project scope

POSIX — user scope

PowerShell — project scope

PowerShell — user scope

Kimi and GLM external routes

Safety and failure behavior

Reference benchmark snapshot

When Model Boss steps aside

Migrating from Token Saver

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages