Corbits Code is built on the same Corbits/Interchange runtime primitives documented across the platform overview: the agent loop, inference, tools, and persistence. It is a consumer of those primitives, not a fork, and the same building blocks are available to you. Its guardrails, though, are layered by Corbits Code: a permission, secret, and authorization system enforced as tool middleware in its own process. They are not the control plane’s credentials and grants.
Install
Homebrew, on macOS and Linux:corbits. Upgrade later with brew update && brew upgrade corbits-code.
To run from source you need Bun 1.2 or newer:
bun run build:bin produces a standalone dist/corbits you can put on your PATH.
Run it
Point Corbits Code at a repository and describe the work. It launches a full-screen terminal UI seeded with your task and starts implementing.What makes it different
Most coding agents stall. They re-read the same files, drift from their own plan, or never signal that they are done. Corbits Code replaces the open-ended chat loop with a deterministic event loop governed by a custom reactor director, a policy layer that watches every turn and decides what happens next.No quiet half-finish
When the agent tries to end a turn with tasks still open, the director rewrites that ending into another inference pass carrying a pointed reminder, up to three times, instead of letting a run stop half-done without saying so.
Tool output stays addressable
The shared Interchange runtime spills oversized tool results to the session blob store and leaves a URI in their place. Corbits Code makes that spill usable: it wires a blob reader into
read_file, rejects the URI on tools that cannot resolve it, and instructs the model to re-open a prior result by reference rather than re-reading the file it came from.A checklist the director holds
The agent tracks its own work as a task list through a dedicated tool. That list lives in director state rather than only in the chat transcript, so it survives context shifts across a long run.
Deterministic loop
The Interchange reactor processes one event at a time and yields a single next action. Corbits Code supplies the policy that picks it: a director written in code, not a suggestion buried in a prompt.
Safety you can’t talk it out of
Corbits Code enforces safety at the tool layer, as middleware wrapped around every tool call, not as advisory text in a prompt the model can reason around. One layer owns each constraint, and the agent cannot evade a constraint by rewording its request.Tiered permissions
Tiered permissions
Read-only tools (reading files, searching, listing directories) run freely. Every consequential tool (file writes, edits, shell commands) is gated. You approve with Allow Once or Allow Always, scoped to a file, a directory, or a command shape. “Allow Always” choices persist per repository, so repeat actions stop interrupting your flow.
Secret guard
Secret guard
Sensitive files are protected by a single hard deny covering two surfaces: path-keyed tool arguments and shell command strings. Both are blocked outright, and the deny runs before the permission gate, so it holds even under
--dangerously-skip-permissions.Path arguments. A tool call whose path argument names a sensitive file is denied: .env and its variants, .dev.vars, anything under .ssh or .gnupg, id_rsa and its ecdsa / ed25519 / dsa siblings, .pem / .p12 / .pfx certificates, .netrc, .npmrc, .pgpass, .htpasswd, .git-credentials, .aws/credentials, and Corbits Code’s own .corbits/settings.json. This covers reads, writes, edits, deletes, and searches pointed at one of those files. Template files like .env.example are exempt.Shell. A run_shell command is tokenized and every path-like token is checked against the same denylist, so cat .env, bun --env-file=.env run …, and FILE=.env cat $FILE are all denied the same as a direct read. There is no operator approval and no “Allow Always” for a secret-path shell command: it is refused. Detection here is token matching, not sandboxing. It defeats quoting and the common assignment and redirection forms, but a path assembled at runtime (for example F=.en; cat ${F}v) is not recognized as one.What the deny does not do. It keys on the path token, not on file contents, so it is not a content filter. A search scoped at a surrounding directory can still surface matching lines from a sensitive file inside it, such as a .pem under certs/, because the search argument names the directory, not the secret file. It also does not cover the Codex and xAI OAuth token files described under Configuration and credentials below: only the literal settings.json filename is matched.Catastrophic-command guard
Catastrophic-command guard
A curated set of unrecoverable commands is blocked before it runs: filesystem creation (
mkfs), raw disk writes (dd to a device), recursive deletes that target the filesystem root, your home directory, or a system tree, writes that clobber system paths like /etc, privilege escalation (sudo), power-state changes (shutdown, reboot), fork bombs, and piping a network download straight into a shell (curl … | bash). Like the secret guard, this cannot be overridden, not even with --dangerously-skip-permissions. Everyday destructive commands like rm -rf ./build aren’t hard-denied here; they go through the permission gate like any other consequential command.Path sandboxing and write verification
Path sandboxing and write verification
Path arguments are resolved against the working directory; paths that escape it are blocked. After every write or edit, the file is re-read and compared to confirm the change actually landed.
Resume where you left off
Conversation context persists to a git-backed store, and director state (turns used, plan, tasks, files read) is snapshotted alongside it. When you relaunch in a repository, Corbits Code can present a session picker in the TUI so you pick up a prior run from exactly where it stopped: no lost context after aCtrl+C, a crash, or a walk away from the desk.
The sub-agent fleet
Corbits Code dispatches specialist sub-agents for self-contained work, each on its own inference source. They form a fleet: a live tree of worker sessions the lead agent spawns, waits on, interrupts, and resumes while they run. The fleet is layered by Corbits Code rather than inherited, implemented under the app’s ownsrc/subagent/ tree.
Authority is a tier, not a prompt
Every profile carries one of three tiers, and the tier decides what it may do to the rest of the tree.Orchestrator
Tier 1, the primary agent. Full fleet control over the whole tree.
Nested orchestrator
Tier 2. May manage only its own descendants, never a sibling and never anything above it.
Leaf
Tier 3, the workers. Each carries an explicit tool allowlist sized to its job, finishes with the report envelope, and mounts no fleet verbs at all.
Picking a specialist
Dispatch by intent and take the default, or name a profile directly. The intent defaults areimplement to build, explore to explore, plan to plan, and review to critique. Naming an id that is not registered fails with the list of valid ones rather than quietly falling back to a general agent.
The registry holds sixteen profiles at v0.3.1. Most are leaves with a narrow tool envelope and a distinct lens: critique reviews for correctness against the brief and cannot finish a run without having read the code it judged, while greybeard judges soundness, constraint ownership, and backward compatibility, and is the one profile besides the primary that can manage a subtree of its own. You can add your own profiles in the project tree or through plugins, and the agent picks the right specialist for the job.
Working a live fleet
Workers are sessions you can steer, not fire-and-forget calls.How a run ends
A worker runs until it produces a report envelope: a structured Summary, Findings, Blockers, and Paths. Short of that, it stops for one of four recorded reasons: it was cancelled by the operator, it hit an opt-in wall-clock deadline, it stalled after a long silence with no tool activity, or it narrated an answer instead of writing an envelope. None of those is a turn count.v0.3.0 removed turn budgets outright, including the maxTurns setting, the per-profile cap, and the argument on the dispatch tools. A worker is bounded by the clock, by its own completion, or by you, and never by a number of inference passes it was allowed to spend.
Integrations
MCP servers
Connect Model Context Protocol servers over stdio (launched as a subprocess) or HTTP (a remote Streamable-HTTP endpoint, authorized via OAuth). Configure them per repo and inspect connected servers with
/mcp.Lifecycle hooks
Config-driven
postTurn and postRun hooks (shell or TypeScript) run automatically. postTurn receives aggregated turn context; postRun receives a run summary. Discovered per repo and globally, and toggled with /hooks.Plugins and skills
Opt-in capabilities: web search, additional tools, workflow recipes. Plugins are discovered per repo, from
.corbits/plugins/, and globally, from ~/.corbits/plugins/. Enabling one is a global choice rather than a per-repo one, because the enable flag travels with any credentials the plugin declares and those live only in the global settings file. Skills are Markdown capability packages the model loads on demand rather than commands you invoke, resolved from enabled plugins first and then from the repo you are working in.Slash commands
An extensible in-TUI command surface:
/model, /settings, /permissions, /plugins, /hooks, /mcp, /cost, /status, /clear, and more. Plugins can register their own.Configuration and credentials
Corbits Code can run on any OpenAI-compatible endpoint, so you bring the model you want: OpenAI, a local Ollama or vLLM server, or an OpenAI-compatible gateway like OpenRouter that fronts Claude, Gemini, and hundreds more. The Corbits runtime speaks to the major model providers natively; Corbits Code reaches models through the OpenAI-compatible protocol. Corbits Code reads its provider and credential configuration from settings files, plus a per-provider token file for OAuth-based providers:Global settings live in
~/.corbits/settings.json (providers and credentials). A per-repo .corbits/settings.json handles selection only: it chooses a provider and model and rejects stored secrets. Codex tokens live in ~/.corbits/codex-auth.json and xAI tokens live in ~/.corbits/xai-auth.json; neither is ever written to settings.json..env files are not loaded, so a stale or exported key can never silently shadow the configured provider. The two settings.json files sit on the secret-guard denylist, so the agent cannot read its own API-key credentials through a file tool or a shell command; the OAuth token files are not on that denylist.
Built on the platform
Corbits Code is the honest test of the platform: everything the runtime provides, it composes; everything it adds sits cleanly on top. That layering is the story.- Composed from the platform
- Layered by Corbits Code
- Agent loop: the event-driven reactor and agent lifecycle
- Inference: the runtime’s inference primitive, run here over OpenAI-compatible sources
- Tools: POSIX shell, file read/write/edit, grep, and search
- Persistence: git-backed context and state storage for resume
Platform overview
The runtime primitives Corbits Code is built on, and how they fit together.
Guardrails
The platform’s Credentials and Grants model: how the control plane keeps agents in bounds.
Workbench
The multiplayer workspace for humans and agents, where a team authors and runs its agents together.