roach-code

Install

Prebuilt binary (no Go toolchain required) — installs from the latest GitHub release:

```sh

Build from source

make build      # -> bin/roach-code
make cross      # -> dist/ (darwin|linux|windows × amd64|arm64)

Quick start

roach-code setup                      # config wizard → ./roach-code.toml
export DEEPSEEK_API_KEY=sk-...  # or put it in ~/.env (see .env.example)
roach-code chat                       # then run /init to generate AGENTS.md (project memory)
roach-code run "implement the TODOs in main.go"
roach-code run --model mimo-pro "add unit tests for this function"
echo "explain this code" | roach-code run

Installed binaries also answer to the short alias roach (e.g. roach chat). A few more commands:

roach-code models                 # list configured providers / models
roach-code models refresh         # re-fetch each provider's model list from its /models API
roach-code codex login            # sign in to Codex with a ChatGPT subscription (OAuth)
roach-code update                 # self-update to the latest release

Configuration

Resolution order: flag > ./roach-code.toml > ~/.config/roach-code/config.toml > built-in defaults. Secrets come from the environment via api_key_env and are never stored in config files.

```toml default_model = "deepseek-flash" # executor; set [agent].planner_model to add a planner

planner_model = "mimo-pro" # optional low-frequency planner

subagent_model = "deepseek-pro" # optional default for runAs=subagent skills

Two-model collaboration (optional)

roach-code setup keeps first-run minimal: pick provider → keys (every SKU of a chosen provider is enabled). Running two models together (executor + planner, separate cache-stable sessions) is a one-line edit afterwards — set planner_model to any other enabled provider:

[agent]
planner_model = "deepseek-pro"   # used as the low-frequency planner

Subagent skills inherit the executor model by default. Set subagent_model to run them on another configured model, or use subagent_models to override only specific skills such as review or security_review.

@ references

Embed @ references in a message and Roach Code resolves them before sending, as tagged context blocks: @path/to/file (or @dir) injects a local file's contents (or a directory listing), and @<server>:<uri> injects an MCP resource. A local path is only treated as a reference when it actually exists, so ordinary @mentions stay literal. Typing / or @ opens an autocomplete menu — slash commands, or hierarchical file navigation (one directory level at a time, descend into folders) plus MCP resources.

Plugins (MCP)

Roach Code is an MCP client. A [[plugins]] entry's type selects the transport: stdio (default) launches a local subprocess (command/args/env); http (Streamable HTTP) connects to a remote url with optional static headers (${VAR} / ${VAR:-default} expanded from the environment, so tokens stay out of the file). Tools surface to the model as mcp__<server>__<tool>; a tool declaring MCP's readOnlyHint: true joins parallel dispatch and the permission reader-default.

A server's prompts surface as /mcp__<server>__<prompt> slash commands (positional args after the command); its resources are pulled in by writing @<server>:<uri> in a message; /mcp lists connected servers and what each exposes. make build also produces bin/roach-code-plugin-example — a runnable reference stdio server (echo, wordcount, a review prompt, a style-guide resource) you can copy.

[[plugins]]                       # local stdio server
name    = "example"
command = "roach-code-plugin-example"

[[plugins]]                       # remote server over Streamable HTTP
name    = "stripe"
type    = "http"
url     = "https://mcp.stripe.com"
headers = { Authorization = "Bearer ${STRIPE_KEY}" }

Already have an .mcp.json? Drop it in the project root and Roach Code reads it as-is — the mcpServers spec (command/args/env, type/url/ headers, ${VAR} expansion) maps field-for-field onto [[plugins]]. Both sources are merged; on a name collision roach-code.toml wins.

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] },
    "stripe": { "type": "http", "url": "https://mcp.stripe.com", "headers": { "Authorization": "Bearer ${STRIPE_KEY}" } }
  }
}