RoboCode

RoboCode is a local-first coding-agent cockpit for developers who want one terminal surface to chat with a model, approve real workspace changes, supervise delegated agents, and keep enough evidence to resume work later.

Chinese version: README.zh-CN.md

Why It Exists

Most coding agents are good at a single conversation. RoboCode is built around a slightly different job: coordinating programming work. It keeps the active conversation, tool effects, approvals, tests, tasks, memory, provider health, and external agent lanes visible in one operator cockpit.

Highlights

• Cockpit TUI: transcript, approval state, workspace snapshot, active tasks, diagnostics, provider health, and recent evidence stay visible together.
• Real tool execution: file read/write/edit, search, shell, web, Git, LSP, test commands, task state, and memory all run through the shared runtime path.
• Permission-aware edits: mutating file, shell, Git, workflow, and delegated agent actions are mediated by permission modes before they affect the workspace.
• Multi-provider runtime: DeepSeek, OpenAI, Anthropic, OpenAI-compatible gateways, Ollama, and offline fallback are available through one provider interface, with provider registry diagnostics.
• Agent supervision lanes: Codex, Claude, custom shell/template lanes, tmux, embedded PTY, and experimental ACP surfaces are exposed as supervised operator lanes.
• Durable local context: transcripts, session index, task events, memory events, lane artifacts, and preview evidence are stored locally by default.
• Screenshot-gated TUI iteration: visual changes produce deterministic screenshots for review before release.
• Multi-platform install: Homebrew plus release archives for macOS, Linux, and Windows.

Screenshots

These are generated from the current RoboCode TUI renderer and kept as release evidence. The screenshots below show the 0.1.23 provider and model setup patch: first-run setup, provider/model configuration, delegated-lane operation, and the daily coding cockpit; the latest published binary release is listed separately in the install section.

Live Provider Turn

Resize-Safe Redraw

CJK Input

Slash-Command Palette

First-Run Setup Wizard

Provider Configuration Selector

Provider Detail Form

Grouped Model Selector

Lane Action Selector

Agent Lane Detail

Side Screen: Agent Lanes

Side Screen: Ops And Evidence

Install

Homebrew Tap

Recommended on macOS and Linux:

brew install wikieden/tap/robocode

Verify the install:

robocode --help

Release Archive

Download a release archive from RoboCode v0.1.23.

Available release targets:

• aarch64-apple-darwin for Apple Silicon macOS
• x86_64-apple-darwin for Intel macOS
• x86_64-unknown-linux-gnu for Linux x64
• x86_64-pc-windows-msvc for Windows x64

Install on macOS or Linux:

VERSION=0.1.23
TARGET=aarch64-apple-darwin
curl -L -O "https://github.com/wikieden/robocode/releases/download/v${VERSION}/robocode-v${VERSION}-${TARGET}.tar.gz"
tar -xzf "robocode-v${VERSION}-${TARGET}.tar.gz"
sudo install -m 755 "robocode-v${VERSION}-${TARGET}/robocode-cli" /usr/local/bin/robocode-cli
robocode-cli --help

Install on Windows PowerShell:

$Version = "0.1.23"
$Target = "x86_64-pc-windows-msvc"
Invoke-WebRequest "https://github.com/wikieden/robocode/releases/download/v$Version/robocode-v$Version-$Target.tar.gz" -OutFile "robocode-v$Version-$Target.tar.gz"
tar -xzf "robocode-v$Version-$Target.tar.gz"
New-Item -ItemType Directory -Force "$env:USERPROFILE\bin"
Copy-Item "robocode-v$Version-$Target\robocode-cli.exe" "$env:USERPROFILE\bin\robocode-cli.exe"
$env:PATH += ";$env:USERPROFILE\bin"
robocode-cli.exe --help

Quick Start

Run RoboCode. Clean installs use DeepSeek as the default online provider and open the cockpit TUI by default:

robocode-cli

If the selected online provider is missing an API key, the TUI opens /setup automatically. You can also use /setup for provider/model setup at any time. The quickest paths are:

/setup
/setup provider
/connect
/models

Set a DeepSeek key for live turns:

export DEEPSEEK_API_KEY="sk-..."
robocode-cli

If the selected model fails or is unavailable, RoboCode shows a switch-model prompt with concrete /model ..., /provider ..., and /provider doctor ... actions.

Run an explicit offline smoke session when you do not want a live provider:

robocode-cli --provider fallback --model test-local

Use the legacy line REPL only when you explicitly need it:

robocode-cli --no-tui --provider fallback --model test-local

Start from source during development:

cargo run -p robocode-cli -- --provider fallback --model test-local

Core Workflows

1. Ask RoboCode to change code, then approve or deny each mutating tool call.
2. Run /test <command> to execute a test through the same permission path and keep failure evidence visible in /status and the TUI.
3. Use /git diff, /diff, and /git status to review what changed before committing.
4. Create a lightweight active brief with /brief <goal> or /spec <goal>; use /brief steering init when project conventions should guide lanes.
5. Track durable work with /task add, /tasks, /task resume-context, and /memory.
6. Open side screens with /screen side-1 and /screen side-2 when you want a second terminal to watch agent lanes or ops evidence.
7. Start supervised external work with /lane codex, /lane claude, /lane run, /lane tmux, or /agent run codex.

Essential TUI Controls

• Enter submits the composer; Ctrl-J is the explicit send action.
• Ctrl-K clears the composer, Ctrl-R reloads the latest user prompt, and Ctrl-N starts /task add ....
• ? opens the in-TUI help surface when the composer is empty.
• Esc or Ctrl-C exits; /quit and /exit also close the TUI.
• While a provider turn is active, the cockpit keeps repainting the working state and elapsed time. Ctrl-C requests cancellation when the runtime can observe it, but an in-flight provider request may still finish.
• Approval prompts default to Approve; press y to approve, n to deny, d to focus diff, or use Tab / arrow keys to move between actions.
• Type / to open command suggestions. /settings, /connect, /provider, /models, /permissions, and /theme open selector-style popups with search, keyboard selection, and mouse selection. Common entries include /help, /settings, /setup, /connect, /provider, /models, /status, /config, /permissions, /test, /sessions, /resume, /task, /brief, /spec, /memory, /lane, /agent, /screen, /lsp, /git, /web, /extensions, /mcp, and /skills. Long suggestion lists keep the selected row visible and support mouse completion on visible rows.

Configuration

RoboCode loads config from the platform config path and then from .robocode/config.toml, with CLI flags taking precedence.

Inside the TUI, /setup opens the first-run provider/model wizard with concrete steps for provider config, model choice, permissions, theme, doctor checks, fallback smoke, and saving defaults. /settings opens an actionable settings picker instead of a read-only status page: provider, model, permissions, theme, save defaults, and diagnostics are all selectable. /connect opens opencode-style provider configuration: choose a supplier first, then inspect auth mode, API-key env vars, endpoint source, diagnostics, save-default actions, and known model candidates on the PROVIDER CONFIG page. Providers can declare different auth modes: OpenAI can be represented as web login or API key, gateway providers such as DeepSeek/OpenRouter use API keys, and local providers such as Ollama/Fallback require no key. Present API keys are shown only as masked prefix/suffix values. Provider detail includes editable rows that complete the composer to /settings provider <id> key-env ..., /settings provider <id> endpoint ..., /settings provider <id> default-model ..., or /settings provider <id> enable-model <model>. The enabled models become the provider's active entries in /models; /settings provider <id> models ... replaces that active list, and /settings provider <id> favorite-model <model> pins a provider/model pair. /models then shows Favorites first, then Recent, then configured-provider groups containing only active models. Favorites are not duplicated in their provider group; Ctrl-F favorites the selected row, and selecting a row switches provider plus model together. /model <model> remains the quick switch for the current provider only. These commands update [providers.<id>] without storing raw API keys.

provider = "deepseek"
model = "deepseek-v4-flash"
permission_mode = "acceptEdits"
request_timeout_secs = 120
max_retries = 2

[providers.deepseek]
api_base = "https://api.deepseek.com"
api_key_env = "DEEPSEEK_API_KEY"
default_model = "deepseek-v4-flash"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
favorite_models = ["deepseek-v4-pro"]

Useful startup flags:

robocode-cli --config .robocode/config.toml
robocode-cli --resume latest
robocode-cli --permissions plan
robocode-cli --tui-theme aurora-cyan
robocode-cli --tui-screen side-1

What Is Experimental

• MCP and skills are visible through /mcp, /skills, and /extensions, but MCP-backed tools are not yet wired into the mutation permission path.
• ACP appears as an experimental agent adapter surface.
• Codex app-server write-capable delegated turns are guarded because live trials showed workspace writes can occur before RoboCode receives an approval event.

Documentation

README stays focused on product usage. Full usage and implementation detail live in the docs:

• User Guide
• Architecture
• Product Requirements
• Long-Term Roadmap
• Staged Roadmap
• Reference Analysis
• Provider Live Matrix
• TUI Cockpit Design
• TUI Interaction Audit
• Testing and Validation Plan
• 0.1.23 Status
• 0.1.21 Plan
• 0.1.21 Status
• 0.1.19 Plan
• 0.1.19 Status
• 0.1.18 Status
• 0.1.17 Plan
• 0.1.17 Status
• 0.1.16 Plan
• 0.1.15 Status
• 0.1.15 Plan
• 0.1.14 Status
• 0.1.14 Plan
• 0.1.13 Status
• 0.1.13 Plan
• 0.1.12 Status
• 0.1.12 Plan
• ContextBundle And Token Efficiency
• Development Standards

Maintainer Checks

Build a local archive:

scripts/package-release.sh

Run the release smoke matrix:

scripts/release-smoke.sh

Generate TUI visual evidence:

scripts/tui-regression.sh docs/previews/generated

After publishing, validate release assets and Homebrew:

scripts/release-smoke.sh --version <version> --github-release-assets --homebrew --skip-package

Every GitHub Release must be paired with a same-version Homebrew tap update. Do not mark a release complete until the post-publish smoke validates both GitHub assets and Homebrew.

Feedback

Please report bugs and feature requests through GitHub Issues.

Helpful issue details:

• RoboCode version or release asset name.
• Operating system and terminal app.
• Provider and model, for example deepseek / deepseek-v4-flash.
• The command you ran and the smallest reproduction steps.
• Relevant logs or screenshots, with API keys and private paths redacted.

License

RoboCode is released under the MIT License. See LICENSE.