supercode

A lightweight, fully-customizable AI coding agent — SDK + CLI, in Rust.

Any model via OpenRouter · natively continues real Claude Code, Codex, Gemini CLI, Goose, Grok, OpenCode, and Pi sessions · a single ~8.4 MB binary.

supercode run "Fix the failing tests, then run pytest -q to confirm."

supercode reads your code, edits it, runs the commands, and confirms the result — streaming every step. It's a native Rust agent loop that talks directly to any model and is built to be a superset of what Claude Code and Codex do.

What supercode is

supercode is the superset glue tool for AI coding agents — the connective tissue between harnesses. It is explicitly not meant to be your primary coder; its value is solving the cross-tool problems no single harness solves: rescue a rate-limited session, migrate a session between tools, and slash the cost of continuing a long session.

Three headline capabilities:

1. Translate between session formats. A universal converter across the declared format set — Claude Code, Codex, Gemini CLI, Goose, Grok, opencode, and pi — load a session in any harness's on-disk format and faithfully emit it in any other, backed by a measured per-pair translation-fidelity matrix and lossless A→B→A round-trips.
2. Emulate-to-continue any harness losslessly. Pick up a real session from harness X, keep running it while emulating X's semantics, and emit it back in X's native format so X's own tool can resume it with no loss.
3. Continue losslessly with massive token reduction — the differentiator. Keep running a session at drastically reduced token cost with zero semantic loss and full reversibility. The rate-limit rescue (hit a limit → reduce + switch provider at minimum cost → continue → export back) is the flagship instance.

Status: Native discovery, import, export, passive follow, and emulate-to-continue are implemented for all seven declared formats. The committed 7×7 fixture matrix measures every format pair and restores exact canonical semantics in all 49 A→B→A runs. Native-only metadata and cross-format raw-byte residue remain named separately; semantic losslessness is not a claim of byte-identical foreign formats. Live runtime operations are only called verified when a current executable receipt proves them; Grok's ACP start/input/events/interrupt/respond/load-session and both Supercode/stock continuation paths are covered by npm run probe:live:grok. The stock-resume matrix additionally proves real stock Claude Code, Codex, OpenCode, Pi, and Grok recall facts from both sides of a GLM 5.2/OpenRouter continuation while the original source stores remain unchanged. ACP load-session resumes persisted history in a new protocol process; it does not attach to an arbitrary already-running TUI. That separate capability is tracked explicitly as runtime.attach_existing_process and remains unsupported where the upstream harness exposes no reachable endpoint. Supercode's own SDK runtime now provides such an endpoint: resume --serve hosts one canonical continuation in an attachable tmux session by default, while ACP, HTTP, and terminal frontends join the same authenticated live process without creating duplicate agents. Tmux is only the local process supervisor; the SDK registry and persisted session family remain authoritative. See ROADMAP.

Rust consumers can take only the layer they need: supercode-interchange for session discovery and translation, supercode-reduce for reversible token reduction, supercode-runtime for provider/runtime primitives, and supercode-harness for Supercode's complete native Agent and tool loop. supercode-core is the backwards-compatible facade and contains no second implementation. See package boundaries.

Why supercode

• 🪶 Light & fast. A single ~8.4 MB static binary (cargo build --release, stripped + thin-LTO, Linux x86_64 — see Cargo.toml release profile); the agent loop runs in ~13–19 MB of RAM — measured ~7× lighter than Codex and ~27× lighter than Claude Code on identical tasks (benchmarks).
• 🔁 A superset. It natively loads, continues, and translates real Claude Code, Codex, Gemini CLI, Grok, opencode, and pi sessions. Resume a session against another provider, then export it back to the source harness.
• 🎛️ Yours to shape. Every prompt, every tool description, and every tool's on/off state is configurable — from CLI flags or the Config builder.
• 🌐 Any model. One OpenAI-compatible provider reaches Claude, GPT, Gemini, Llama, DeepSeek — anything OpenRouter routes to, or any endpoint you point it at.

Install

curl -fsSL https://raw.githubusercontent.com/volter-ai/supercode/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/volter-ai/supercode/main/scripts/install.ps1 | iex

The install scripts pull checksum-verified prebuilt binaries from GitHub Releases. Building from source with cargo install supercode-cli remains available on platforms without a prebuilt asset.

Prebuilt channels resolve to GitHub Releases. Building from source needs Rust 1.85+.

curl -fsSL https://raw.githubusercontent.com/volter-ai/supercode/main/scripts/uninstall.sh | sh

irm https://raw.githubusercontent.com/volter-ai/supercode/main/scripts/uninstall.ps1 | iex

By default this removes only the binary (and the PATH line install.sh may have added to your shell rc) — your config, credentials, MCP registry, and session history under ~/.config/supercode are left alone. Add --purge to remove those too, and --dry-run to preview either mode without deleting anything:

sh scripts/uninstall.sh --dry-run          # preview: binary + PATH line only
sh scripts/uninstall.sh --dry-run --purge  # preview: + config/credentials/sessions
sh scripts/uninstall.sh --purge            # prompts, then removes everything

Windows (scripts/uninstall.ps1, same flags as -DryRun / -Purge / -Yes):

.\uninstall.ps1 -DryRun            # preview: binary + user-PATH entry only
.\uninstall.ps1 -DryRun -Purge     # preview: + config/credentials/sessions
.\uninstall.ps1 -Purge             # prompts, then removes everything

Installed via cargo install? The uninstaller detects this and runs cargo uninstall supercode-cli for you. Homebrew or npm installs are managed by their own package manager (brew uninstall supercode / npm uninstall -g supercode) — the script tells you which applies rather than reaching into those directories itself. Full details: Install & setup → Uninstall.

Platform support (from the release build matrix, .github/workflows/release.yml):

Install supercode, a Rust CLI coding agent, and verify it works:

1. Install it with one of:
   - curl -fsSL https://raw.githubusercontent.com/volter-ai/supercode/main/scripts/install.sh | sh
   - cargo install supercode-cli   (needs Rust 1.85+; use this on a platform
     without a prebuilt release asset)
2. Confirm it's on PATH: `supercode --version`
3. Set an API key: `export OPENROUTER_API_KEY=sk-or-...` (or run `supercode login`
   to save it interactively), then run `supercode doctor` and confirm every line
   is green, especially `provider: reachable (200)`.
4. Try it: `supercode run "list the top-level files in this repo"`.

If `supercode doctor` reports a missing key or an unreachable provider, stop and
tell me the exact output rather than guessing at a fix.

Quickstart

supercode login          # paste your OpenRouter key → ~/.config/supercode
supercode doctor         # ✓ config, key, and live provider reachability
supercode run "summarize this repo's module layout"

No key yet? Any of: supercode login, export OPENROUTER_API_KEY=sk-or-…, or --api-key. On a genuinely fresh install with no config yet, an interactive run/chat/resume walks you through this automatically (detects an existing key/env var, lets you pick a default model, and finishes with a doctor check) — it runs at most once and never fires on a non-interactive or scripted invocation, so the copy-paste block above still works unattended.

Health check — supercode doctor

Corpus audit — supercode audit

The superpower: continue any session, in any model

supercode treats sessions like an image editor treats files — one canonical in-memory model, importers and exporters for each format.

# Continue a Claude Code transcript with GPT-5:
supercode --model gpt-5 resume ~/.claude/projects/<proj>/<id>.jsonl "finish the refactor"

# Continue a Codex rollout with Claude Opus:
supercode --model opus resume ~/.codex/sessions/.../rollout-*.jsonl

# Inspect or convert any session — no API key needed:
supercode inspect <session>.jsonl
supercode convert <claude-session>.jsonl --to codex -o as-codex.jsonl

# Follow normalized messages while another harness writes the session:
supercode watch <session>.jsonl

resume auto-detects the format and normalizes it to a provider-neutral history, so a conversation that started in one tool continues seamlessly in another model. watch passively emits snapshots and appended messages as NDJSON; it observes persisted session state and does not attach to or control the harness's terminal. → Sessions & interop · Resume & format-detection reference

Use it as a library

use supercode::{Agent, Config};

let config = Config::builder()
    .model("anthropic/claude-opus-4-8")
    .system_prompt("You are a terse, expert pair programmer.")
    .disable_tool("bash")                          // toggle tools off…
    .tool_description("search", "Grep the repo.")  // …or re-describe them
    .build();

let mut agent = Agent::new(config)?;
let reply = agent.send("Find every TODO and group them by file.").await?;
println!("{reply}");

Register your own tools by implementing Tool. → SDK guide

Built-in tools

read_file, write_file, edit_file, list_dir, glob, search (regex, gitignore-aware), apply_patch, bash, shell (persistent), update_plan — each disableable and re-describable. Writes are sandboxed (the CLI defaults to workspace-write; the library defaults to full access unless you set .sandbox(...); on macOS the OS seatbelt confines bash too). Full breakdown of what each sandbox/approval mode actually enforces: → Safety.

Privacy

supercode sends no telemetry, ever — no analytics, no usage pings, no phone-home, on any command. The only outbound network calls a run/chat/ doctor/resume makes are to the model provider you configured (--base-url, default OpenRouter) and, if you've wired one up, an MCP server you configured yourself. inspect/convert/watch make no network calls at all. This is a stronger claim than an opt-out — there is no telemetry sink to opt out of. See Install & setup → Privacy for the grep-able verification.

Documentation

Benchmarks & footprint

"Light and fast" is measured, not asserted — supercode's own footprint is measured on every bench run; the cross-harness comparison below was measured once, see the caveat after the table for what that means for reproducibility. bench/ runs the agent against a live model and profiles the harness's own footprint (peak RSS, CPU, startup, binary size). Same model (DeepSeek V4 Flash via OpenRouter), same tasks, same verifier, same per-process sampler — only the harness changes:

The codex/claude columns above are a one-time measurement on the author's machine, off-repo — rerunning compare_harnesses.py needs the codex and claude binaries installed locally plus a live OpenRouter API key, so the comparison is not reproducible from a clean checkout. The committed evidence is bench/suites/harness-comparison.json and the methodology write-up at bench/suites/harness-comparison.md. The supercode own-process numbers, by contrast, are measured on every bench run via getrusage.

All three solved the same tasks; supercode also used the least CPU. On a real subset of the Aider polyglot benchmark (12 Exercism exercises across Python/Rust/Go) supercode driving DeepSeek V4 Flash scores 12/12. Full methodology and per-task data: bench/; full comparison methodology and caveats: bench/suites/harness-comparison.md.

Startup latency — jcode's README also reports time-to-first-frame / time-to-first-input against its competitors; here's the same axis for supercode. Unlike the RSS table above, this needs no API key — it times process spawn to first PTY output on each tool's --help (network-free, so it's reproducible from a clean checkout with just the binaries installed):

This is a cold-start proxy (--help, not a live chat frame): supercode's chat command gates all rendering behind require_api_key(), so a true first-chat-frame or first-input-echo number would need live credentials (or a mock completion endpoint) for all three tools — not set up here, and the table above should not be read as chat responsiveness. Raw data bench/suites/startup-latency.json, methodology and the full caveat: bench/suites/startup-latency.md.

export OPENROUTER_API_KEY=sk-or-...
cargo run -p supercode-bench -- --tasks bench/suites/polyglot --sandbox danger-full-access
python3 bench/tools/compare_harnesses.py     # supercode vs claude vs codex (RSS, needs API key)
python3 bench/tools/startup_latency.py       # supercode vs claude vs codex (startup latency, no API key needed)

Or reproduce a scorecard end to end with one command — scripts/run-benchmarks.sh prints toolchain/git-SHA provenance, always measures the real release-binary size (no API key needed), and (with OPENROUTER_API_KEY set) runs a suite and writes a timestamped scorecard under bench/results/; see bench/README.md.

Status

Implemented and tested: OpenRouter / OpenAI-compatible streaming provider with tool calls · built-in tool suite + per-tool customization · agent loop with streaming events and an iteration budget · native Claude Code and Codex session loading + continuation · saving / converting sessions back to both formats. Written files have been manually verified resumable by the stock claude and codex binaries (a one-off check, not part of CI).

Not yet built (natural next steps): a lossless native session format, richer prompt-cache controls, and Linux (landlock/seccomp) sandboxing — the OS process sandbox is macOS-only today. See ROADMAP.

License

MIT OR Apache-2.0.