> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corbits.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Corbits Code

> Corbits Code is a terminal-based coding agent built on the Corbits agentic platform — the flagship example app that proves the runtime primitives in production.

Corbits Code is a single-process, terminal-based coding agent that plans, writes, and tests code locally on your machine. You give it a task in plain English and it works autonomously, reading files, writing code, running tests, and driving a feature to completion. It runs on the model of your choice: Claude, GPT, Gemini, or any other model served over an OpenAI-compatible endpoint. It is deeply extensible, through MCP servers, hooks, plugins, skills, and reviewer sub-agents.

It is also the clearest proof that the Corbits agentic platform holds up under real load. Corbits Code is not a demo stub: it is a production coding agent assembled entirely from the platform's runtime primitives, then layered with the discipline, safety, and UX that make an agent trustworthy. If you want to see what you can build on the platform, this is the reference.

<Note>
  Corbits Code is built on the same Corbits/Interchange **runtime primitives** documented across the [platform overview](/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 — not the control plane's credentials and grants.
</Note>

## 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.

```bash theme={null}
corbits "Add JWT auth to the API"
```

From there you steer in chat: answer the agent's clarifying questions, approve consequential actions, and follow along in the live event log as it edits files and runs commands.

## 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.

<CardGroup cols={2}>
  <Card title="No quiet half-finish" icon="gauge-high">
    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.
  </Card>

  <Card title="Tool output stays addressable" icon="link">
    The shared [Interchange runtime](/platform/overview) 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.
  </Card>

  <Card title="A checklist the director holds" icon="list-check">
    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.
  </Card>

  <Card title="Deterministic loop" icon="arrows-rotate">
    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.
  </Card>
</CardGroup>

## 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.

<AccordionGroup>
  <Accordion title="Tiered permissions" icon="shield-halved">
    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.
  </Accordion>

  <Accordion title="Secret guard" icon="key">
    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.
  </Accordion>

  <Accordion title="Catastrophic-command guard" icon="explosion">
    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.
  </Accordion>

  <Accordion title="Path sandboxing and write verification" icon="lock">
    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.
  </Accordion>
</AccordionGroup>

Consequential actions run through an ask/auto behavior at the permission gate, so you decide how much to approve interactively versus let run. That setting never downgrades the secret guard or the catastrophic-command guard: both are hard denies that hold regardless of how much you choose to auto-approve.

## 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 a `Ctrl+C`, a crash, or a walk away from the desk.

## Reviewer sub-agents

Corbits Code ships built-in sub-agent profiles the agent can dispatch for a self-contained subtask on a separate inference source:

<Columns cols={2}>
  <Card title="greybeard" icon="user-graduate">
    A seasoned-architect reviewer — checks design, constraint ownership, and backwards compatibility.
  </Card>

  <Card title="critique" icon="magnifying-glass">
    A code-quality reviewer — tests assumptions, hunts edge cases, and flags security smells and untested paths.
  </Card>
</Columns>

You can add your own profiles in the project tree or through agent plugins; the agent discovers them and picks the right specialist for the job.

## Integrations

<CardGroup cols={2}>
  <Card title="MCP servers" icon="plug">
    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`.
  </Card>

  <Card title="Lifecycle hooks" icon="webhook">
    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.
  </Card>

  <Card title="Plugins and skills" icon="puzzle-piece">
    Opt-in capabilities enable per workspace — web search, additional tools, workflow recipes. Skills are Markdown capability packages the model loads on demand rather than commands you invoke.
  </Card>

  <Card title="Slash commands" icon="terminal">
    An extensible in-TUI command surface — `/model`, `/settings`, `/permissions`, `/plugins`, `/login`, `/mcp`, `/clear`, and more. Plugins can register their own.
  </Card>
</CardGroup>

## 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 only:

<Info>
  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.
</Info>

Credentials come exclusively from these files. There is no environment-variable override and `.env` files are not loaded, so a stale or exported key can never silently shadow the configured provider. Both settings files sit on the secret-guard denylist, so the agent cannot read its own credentials through a file tool or a shell command.

## 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.

<Tabs>
  <Tab title="Composed from the platform">
    * **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
  </Tab>

  <Tab title="Layered by Corbits Code">
    * Custom **reactor directors** for stall detection, plan adherence, and completion discipline
    * A **permission, secret, and authorization** system enforced as tool middleware
    * An **Ink-based terminal UI** with a live event log, diff view, and modals
    * Workflows, hooks, plugins, skills, and reviewer sub-agents
  </Tab>
</Tabs>

The same primitives that make Corbits Code fast, safe, and resumable are the ones the platform exposes to you.

<CardGroup cols={2}>
  <Card title="Platform overview" icon="layer-group" href="/platform/overview">
    The runtime primitives Corbits Code is built on, and how they fit together.
  </Card>

  <Card title="Guardrails" icon="shield-check" href="/platform/guardrails">
    The platform's Credentials and Grants model — how the control plane keeps agents in bounds.
  </Card>

  <Card title="Workbench" icon="screwdriver-wrench" href="/platform/workbench">
    The multiplayer workspace for humans and agents, where a team authors and runs its agents together.
  </Card>
</CardGroup>