RedDB's terminal coding agent.
Secrets the model uses but never sees, a second mind that checks the first, and an autonomous fleet on screen next to your session.

---

Redcode is reddb.io's coding agent for our own engineering work. It is built on OpenCode: its agent loop, providers, tools and terminal UI are the foundation this stands on. Attribution is preserved in NOTICE.

What Redcode adds

	Feature	In one line
🔐	Vault	Per-project secrets the model can use, obtain and ask for without seeing the value
🧠	S1 · S2 reasoning	A second model evaluates the first with typed questions
🎯	/goal	A definition of done pursued across turns, judged every turn
🎨	Design mode	Prototype in the browser, review it there, leave with a plan
🧭	Modes	Build, plan, design and question: four agents, one Tab apart
🔀	RedRouter	One key, many providers, with pinned offers and an auto variant
👁	Monitors	Background watches the agent starts, in one tab
🛠	Workers	The RedSkills fleet as a tab in your session
🛑	Stop-loss	Halts a stuck or runaway agent without punishing progress
🗜	Compaction	Focused, anchored, background, and free of secrets
🌿	Worktrees and service	Isolated worktrees per task, and a server that outlives the TUI
🎙	Dictation	Speak into the composer; you decide when it is sent

Install

npm install -g @reddb-io/redcode
redcode

With mise, which installs the release binary straight from GitHub and needs no Node:

mise use -g github:reddb-io/redcode@latest

Native archives for Linux, macOS and Windows are also on the Redcode releases page. Each includes redcode and redcode-rpc-sidecar; checksums are in SHA256SUMS. Keep one installation method per machine.

Use

Command	Purpose
redcode	Open the terminal UI
redcode --yolo	Open with automatic permission approval
redcode --tmp	Work in a throwaway worktree
redcode setup or /setup	Configure and check S2 and optional S1
/intelligence	Inspect selected models and session evaluations
/design	Switch to Design mode
/design-open	Resume a Design conversation
/design-review	Open the current conversation's browser review
/goal	Start, inspect or control a session goal
/vault	Manage this project's secrets
/monitors	List the session's background monitors
/workers	Inspect the RedSkills worker fleet
/worktrees	Manage the project's git worktrees
/budget	Set an optional spend or token budget
redcode vault set|import	Store a secret, or import a .env file
redcode service	Control the background server
redcode run	Run a prompt without the full TUI
redcode serve	Run the HTTP server
redcode acp	Run the Agent Client Protocol integration
redcode --help	List CLI commands

Modes

A session runs one of four primary agents. Tab cycles through them (Shift+Tab goes back), and the switch is durable: the next prompt is admitted under the agent you picked. Each mode is a different answer to what the agent is allowed to touch.

Build is the default. It reads, edits and runs under the permissions you configured, and it delegates to subagents when the work fans out. The other modes are defined by what they take away from it.

Plan reads everything and changes nothing but the plan file. Use it when the shape of the work is the question: the agent explores, asks and writes the plan down, and plan_exit asks whether to switch to build and start on it.

Design is for when the question is what something should be, not how to build it. See Design mode.

Question answers investigative questions about the codebase with read-only tool access. Nothing is edited.

Vault

Agents need credentials to do real work: call an API, log in and fetch a token, push to a registry. They should not need to read them. The vault keeps secrets per project and lets the model work with a reference such as {vault:github-token} instead of the value.

• Pasting a secret is safe. A high-confidence secret in your prompt is moved into the vault before anything is stored, and the transcript, the event log and the model only ever see the reference.
• The model can use a secret. References in shell commands and env-style file writes are resolved by the harness at the last step, in a way that survives shell quoting. Tool output is scrubbed of every known value on the way back.
• The model can obtain one. A token that a tool prints, such as a login response, is captured automatically, so the next call can use it without the value ever entering the context.
• The model can ask for one. vault_request opens a masked input for you. The model gets a reference back.
• Hosts are bound. The first time a secret is used against a host, you are asked once; after that the secret only goes where you approved.
• The model is told how. The harness explains the vault to the model in its instructions, and lists the names it may use, never the values.
• Restricted content is flagged. S1 marks messages that carry restricted content, protects them, and tells you the secrets were removed from the context. /compact and session titles pass through the same redaction.

A project's secrets live where your project already keeps them: the .env file at the root of the repository, which Redcode adds to .gitignore. GITHUB_TOKEN in the file is {vault:github-token} in a prompt, a pasted GITHUB_TOKEN=ghp_… is written back under that name, and edits you make to the file are picked up while a session runs. Worktrees share the main checkout's .env. Only variables named like credentials, or holding a recognized secret, are hidden from tool output, so PORT stays readable. A token the agent captured from a tool's output is short-lived and stays in memory only.

Manage secrets with /vault, redcode vault set NAME (masked prompt, or a piped value), or redcode vault import other.env. Vault coverage is measured in CI against a 90% line target.

S1 · S2 dual reasoning

S2 generates responses and does the agent work. S1 evaluates candidates with typed TypeSafe/JEV questions, so a claim is checked before you trust it. Single reasoning uses S2 alone; dual adds S1. Run /setup (or redcode setup) to pick and check the models, and /intelligence to inspect the current models, the effective mode and recent evaluations. An unavailable, inconclusive or rejected evaluation is shown as such, never as an approval. See reasoning roles.

Goal

Every mode is turn by turn: the agent answers, the harness waits for you. /goal changes that for one session. You give it a definition of done, and the harness keeps the agent on it across turns until it holds, until it is blocked, or until the budget runs out.

/goal make the design suite pass; verify: bun test test/design; gate: bun test test/design;
constraints: do not touch the app package; stop when: a test needs a network

Free text is the objective. The optional fields, one per line or separated by ;, are the contract the judge holds the agent to:

Field	What it fixes
outcome: / done when:	What has to be true at the end
verify:	How the agent should prove it
gate:	A shell command that must exit 0 before the goal can be judged done; several allowed
constraints: / scope:	What may not be touched or changed
stop when:	What should make the agent stop and ask instead of pushing on

At the end of every turn the gates run, and a failing gate feeds its output into the next turn. Then a small judge reads the objective and the last answer and says DONE, CONTINUE, BLOCKED or WAIT. The objective lives in session metadata, not the transcript, so compaction cannot paraphrase it away. The agent may claim completion with goal_complete, but the next judgement consumes that claim rather than trusting it. Ctrl+C pauses a goal, and so does a new process: a loop never restarts itself. /goal-pause, /goal-resume and /goal-drop do what they say.

Design mode

Design mode is for working out what something should be by building it. The agent writes an interactive prototype, you review it in your browser, and what you decide becomes a plan. The agent cannot edit the product in this mode, only the prototype, so nothing you say changes code until you leave.

• Targets. Prototype for the web, for an app, or as presentation slides.
• Review in the browser. Click an element, select text or a diagram node and leave a note. Nothing reaches the agent until you press Send to Agent. The page reloads when the agent saves and keeps your place.
• Layout audit. After every load the browser looks for cut-off text, controls outside the viewport and sideways scrolling. You choose which findings to queue as fixes.
• Whiteboard. Mermaid diagrams open in an Excalidraw whiteboard; your edits go back as a note and a PNG.
• Your design system. The agent reads DESIGN.md (or .red/DESIGN.md) and reuses the project's real components. Set design.system in redcode.json to point at it.
• Finish. design_exit writes the plan from the decisions and open questions recorded in design.json.

Prototypes live in .redcode/designs/<name>/. redcode serve --hostname 0.0.0.0 lets you review from a phone.

RedRouter

RedRouter is a provider that fronts many models behind one key. Redcode understands it natively: an auto variant lets the router choose, pinned offers fix a model to a specific provider, model suggestions surface what your key can reach, and the router's MCP tools are registered for you.

Monitors

When the agent starts something that should keep running, such as a dev server, a build or a poll, it starts a monitor instead of sleeping in a loop. /monitors lists them in one tab with their state, and the session is woken when one finishes or expires.

Workers

Redcode integrates natively with RedSkills and its host-scoped redskilled daemon. The Workers view is a live, project-scoped console: each worker's identity, process and time, an activity feed of arrivals and departures, and project controls such as drain, stop and status. Redcode keeps no separate control state; the daemon owns it.

Stop-loss and loop guard

Two safety nets watch every session. The loop guard notices an agent repeating the same call with the same result. The stop-loss notices a session that keeps spending without making progress. Both were calibrated to ignore normal work: an edit acknowledgement is not a repeat, and cached context is not spend growth. There are no default cost limits. /budget sets a limit only when you ask for one, and a model can never set its own.

Compaction

/compact can take a focus (/compact keep the migration steps), runs in the background, and keeps anchors: the user messages and decisions that must survive verbatim. Its output passes through the same redaction as the vault, so a secret pasted earlier in the chat does not come back in the summary. /restricted lists the messages marked as restricted content and lets you remove one from the context.

Worktrees and the background service

redcode --tmp starts in a throwaway git worktree, and /worktrees (or redcode worktrees) lists, creates, refreshes and cleans the project's worktrees. The server that holds your sessions can run in the background, so closing the terminal does not stop them: redcode service status|start|stop|restart. If it fails to start, the message says why.

Dictation

The composer accepts structured dictation from dit over a local, process-scoped socket. Partial text is replaceable, committed segments accumulate, and finishing leaves an editable draft. Voice input never submits the composer. See voice input.

Development

Current implementation lives in packages/core, packages/cli, packages/tui, packages/server, packages/protocol and packages/schema. packages/redcode packages the CLI as Redcode. Internal @opencode/* package names preserve the upstream architecture and do not change the published product name.

main is the development branch. Run bun run check for lint and type checking. Tests run from package directories, never the repository root. Regenerate the client with bun run generate in packages/client after changing the public API. The README artwork is generated: bun script/readme/banners.ts rewrites docs/hero.svg and docs/features/*.svg.

Releases

Publish through the redcode workflow:

gh workflow run redcode.yml --repo reddb-io/redcode --ref main -f publish=true

The workflow runs checks and tests, builds native CLI/sidecar and Design archives, publishes npm packages, verifies installation and checksums, then publishes the GitHub releases. Changesets record release intent for @reddb-io/redcode; the workflow versions and publishes directly from main. See CI/CD.

License

MIT. See LICENSE and NOTICE.