blyte: a lean coding-agent harness

CI Docs License: Apache-2.0 Rust stable macOS and Linux

**blyte is the implementer you put under a frontier model.** Plan with Claude Code (or any frontier harness), then hand each well-specified task to blyte running on a cheap model. blyte does the work in its own git worktree, and the repository's own check, run as a **sealed gate**, decides whether it is done. The frontier model reviews the diff and merges. ```mermaid flowchart LR P["Frontier model
(Claude Code)
plan: split into tasks
with disjoint files"] subgraph par ["blyte dispatch, in parallel: one worktree and one gate each"] direction TB T1["T1 · .wt/T1
blyte (cheap model)
implement, commit"] --> G1{{"gate"}} T2["T2 · .wt/T2
blyte (cheap model)
implement, commit"] --> G2{{"gate"}} T3["T3 · .wt/T3
blyte (cheap model)
implement, commit"] --> G3{{"gate"}} G1 -. "fail: retry" .-> T1 G2 -. "fail: retry" .-> T2 G3 -. "fail: retry" .-> T3 end P -- "task + tests" --> T1 P -- "task + tests" --> T2 P -- "task + tests" --> T3 G1 -- "JSON summary" --> R["Frontier model
review each diff
as it lands"] G2 -- "JSON summary" --> R G3 -- "JSON summary" --> R R -- "merge one by one,
rebase if main moved" --> M[("main")] ``` Your frontier tokens go on the parts that need judgement: planning and review. The typing, test-running and fixing runs on a cheaper model, inside a harness built to waste as little of it as possible. In a first check against Claude doing the same work itself, Claude spent about a third as much when blyte implemented, for the same result. blyte took longer; independent tasks run in parallel, and adding blyte agents adds little frontier usage. This is how blyte itself is built. **Get started:** [install blyte](#install) and run `blyte skill install`. From then on Claude Code writes the plan and hands the implementation to blyte, independent tasks in parallel, checking each result. [The workflow](docs/orchestration.md) explains what happens. | | | |---|---| | **0.52×** the time, **0.63×** the cost | as an implementer, against agy (Google's Antigravity CLI) on the same 37 tasks, same model, same commit, both driven by Claude | | **19 / 27** FrontierHarness tasks | blyte on its own on Gemini 3.8 Flash, no plan; the best published Kimi K3 configuration passed 17 / 27 | Both come with caveats (one model, our own repositories, a single run on a different model from the leaderboard's), and the comparison against a frontier model doing the whole task itself so far covers one task. [The evidence page](docs/evidence.md) has the method and all the caveats. Named after rust fungus (the blight Rust is named after), and bytes. ## Why blyte - **"Done" means something.** `--gate` is a command, not a tool: the model cannot call it, skip it or grade itself. Every step of a multi-line gate runs and every failure comes back at once. A failed attempt can roll back to where the run started. - **The turn is the unit of cost, so blyte saves turns.** Whole-file reads, all gate failures in one message, quick checks before the slow ones, and an append-only prompt that keeps the provider's cache valid, with old turns folded into a harness-written digest. - **The harness gets out of the way.** A persistent shell session costs about 0.7 ms per command; `grep` and `glob` run in-process on ripgrep's libraries; no tool result can flood the context. - **Sandboxed by default.** Commands cannot write outside the workspace (macOS Seatbelt, Linux Landlock), read credential stores or `.env` files (macOS), or see credential-looking environment variables; `--network=off` keeps code on the machine. - **Honest numbers.** `--report` writes one JSON record per run: outcome, turns, true cost, per-call usage, where the time went, and the run's security settings. - **Small on purpose.** Features that did not win in measurement (a daemon, an MCP server, a planner, a TDD mode, LLM summaries, …) were deleted. [The manifesto](MANIFESTO.md) explains the rules. ## Install ```bash cargo install blyte --locked export GEMINI_API_KEY=... # the implementer's model; see Providers for others ``` ## Quick start: with Claude Code ```bash blyte skill install # the skill, default model choice, and blyte as Claude Code's default implementer ``` That's all. `blyte skill install` asks which default implementer model to save as `BLYTE_MODEL` in `~/.config/blyte/env` (or pass `--model ` to set it without asking). Ask Claude Code for a change as usual. It splits the work into independent tasks, runs `blyte dispatch` for each **in parallel** (one worktree each, your check command as the gate), reads each JSON summary, reviews each diff with `blyte review` and merges them in order. - `--model ` writes `BLYTE_MODEL=` to `~/.config/blyte/env` without asking (for an Argon model, also `BLYTE_MODEL_TIMEOUT_SECS=600`). - `--project` installs into the current repository instead (committed, so everyone gets it). - `--no-default` installs the skill without making blyte the default; then ask for it: *"Plan this change, then use blyte to implement each task and review the results."* - In `~/.claude/settings.json`, global install sets the status line (`--no-statusline` skips it) and sets `autoCompactWindow` to `200000` unless an auto-compact window is already set (`--no-autocompact` skips it). - `blyte skill uninstall` removes the skill, both `CLAUDE.md` blocks, the status line, and the `200000` `autoCompactWindow` if blyte set it and it has not been changed. - `--harness codex` (or `all`) sets up Codex CLI the same way: skill, `AGENTS.md` block, and rules that let `blyte dispatch` run outside Codex's sandbox. Run end to end with Codex CLI on 2026-09-30. Any other orchestrator can do the same: `blyte dispatch` takes a task file and a gate and prints JSON, and `blyte skill print` prints the instructions. ## Watch what's running ```bash blyte dashboard --open # http://127.0.0.1:7171, this machine only ``` The dashboard has two tabs. **Jobs** shows one row per job across your repositories: what it is doing now, time, cost and turns, with the running ones first, the last 24 hours below, and a **Needs attention** filter for failed runs nobody has dealt with yet. Click a row for the task, gate failures, worktree and log; click a tag (repo, plan, harness, A/B pair) to see the jobs that belong together. **Plans** shows each plan file with a task running now, drawn as a flow of its tasks: lanes by area of code, columns by dependency order, each task coloured by its state; click a task for its run. It reads the files `blyte dispatch` already writes, so there is nothing to set up: it shows every repository blyte has worked in on this machine. You can also list repository folders in `~/.config/blyte/dashboard.toml` ([Dashboard](docs/usage.md#dashboard)). ## Quick start: blyte on its own ```bash # A gated run: exits 0 only when the check passes blyte "fix the off-by-one in the lexer" --gate "cargo test -p lexer" # A gate of several steps: all run, all failures are reported together blyte "handle empty input in parse()" --gate 'cargo fmt --all --check cargo clippy --all-targets -- -D warnings cargo test' # Budgets and a machine-readable report blyte "$(cat task.md)" --gate "pytest" --max-seconds 1800 --max-cost 2 --report run.json # Inside a running container blyte "make the migration idempotent" --gate "pytest tests/test_migrations.py" \ --container my-dev --container-workdir /app # Keep the code on the machine blyte "..." --gate "cargo test --offline" --network=off ``` > [!WARNING] > With rollback on (the default), a failed gate resets the tree to the commit the run started > from, discarding uncommitted changes. Start from a clean tree, or run blyte in its own worktree. ## Providers The model name (`--model` or `BLYTE_MODEL`) picks the provider: | model name | provider | credentials | |---|---|---| | `gemini-4-argon` (recommended), `gemini-3.8-flash-high` (built-in default) | Google Gemini (`-low`/`-medium`/`-high` thinking) | `GEMINI_API_KEY` | | `claude-…`, `anthropic/…` | Anthropic, with prompt caching | `ANTHROPIC_API_KEY` | | `openai/` | any OpenAI-compatible API, including local vLLM / LM Studio | `OPENAI_API_KEY`, `OPENAI_BASE_URL` | | `openrouter//` | OpenRouter | `OPENROUTER_API_KEY` | | `:`, `ollama/…` | Ollama, local or cloud | `OLLAMA_HOST` or `OLLAMA_API_KEY` | | `chatgpt/` | a ChatGPT subscription, via the Codex CLI's login | `~/.codex/auth.json` (read only) | `blyte skill install` asks for your default model (`gemini-4-argon` recommended, `gemini-3.8-flash-high`, or any model id) and writes `BLYTE_MODEL` to `~/.config/blyte/env` (or pass `blyte skill install --model `); for an Argon model it also writes `BLYTE_MODEL_TIMEOUT_SECS=600`. Credentials are read by blyte and never reach the commands the model runs. Details: [docs/providers.md](docs/providers.md). ## Documentation | | | |---|---| | [Getting started](docs/getting-started.md) | install, set up Claude Code, the first delegated task | | [blyte as your implementer](docs/orchestration.md) | the plan → delegate → review workflow, and when to use it | | [How tasks are written](docs/writing-tasks.md) | what the orchestrating agent writes for blyte, and why | | [Running tasks](docs/usage.md) | the gate, budgets, rollback, containers, standalone runs | | [Security and the sandbox](docs/security.md) | what commands can and cannot reach, per platform | | [Run reports](docs/reports.md) | every field of `--report` | | [How it works](docs/how-it-works.md) | the loop, folded context, the tools | | [Evidence](docs/evidence.md) | the paired runs, FrontierHarness, and their caveats | | [Manifesto](MANIFESTO.md) | fast and good, no bunk | The docs are also a site: `uvx --with mkdocs-material mkdocs serve`. ## Contributing Contributions are welcome; read [CONTRIBUTING.md](CONTRIBUTING.md) first. The short version: the checks are `cargo fmt --all --check && cargo clippy --all-targets -- -D warnings && cargo test --workspace --all-targets`, and a claim that something is faster needs a paired measurement. Security reports: [SECURITY.md](SECURITY.md). ## License Licensed under the [Apache License 2.0](LICENSE).