rust-code

rust-code is a terminal coding agent written in Rust.

It combines a Ratatui-based TUI, typed tool execution, fuzzy navigation, session history, and an SGR-driven agent loop so you can work on a codebase without leaving the terminal.

Install

Homebrew (macOS, auto-installs tmux):

brew install fortunto2/tap/rust-code

One-liner (downloads binary + installs dependencies via doctor):

curl -fsSL https://raw.githubusercontent.com/fortunto2/rust-code/master/install.sh | bash

From crates.io:

cargo install rust-code
rust-code doctor --fix   # installs tmux, ripgrep, etc.

Run it:

rust-code                                          # interactive TUI
rust-code -p "Find the bug in src/main.rs"         # headless mode
rust-code --resume                                 # continue last session
rust-code --resume "refactor"                      # fuzzy-search sessions by topic
rust-code -p "build feature X" --loop 5            # autonomous loop (BigHead mode)
rust-code -p "improve yourself" --evolve           # self-evolution mode

Features

• Interactive TUI — chat UI built with ratatui and crossterm
• SGR agent loop — typed tool execution with fallback chain (Gemini Pro → Flash → Flash Lite)
• 22 built-in tools — file read/write/edit/patch, bash (fg + bg), search, git, memory, tasks, agent swarm, MCP, OpenAPI
• Agent swarm — spawn child agents with roles, wait/cancel, parallel task execution
• Task management — persistent kanban board via .tasks/*.md
• Fuzzy file search (Ctrl+P) — fast file navigation with nucleo and live file preview
• Project symbol search (F6) — browse functions, structs, enums with code preview
• Background tasks (F7) — run long commands in tmux windows with realtime output preview
• Skills system (F9) — browse, search, and install agent skills from skills.sh registry
• MCP support — connect external tool servers via .mcp.json (e.g. Playwright, codegraph, Supabase)
• OpenAPI → Tool — any API as one tool: load spec → fuzzy search endpoints → call. 10 popular APIs pre-configured (GitHub, Cloudflare, Stripe, OpenAI, etc.) + APIs.guru directory (2800+ APIs). TOML registry at ~/.sgr-agent/apis.toml
• Git integration — diff sidebar, history viewer, stage and commit from the agent
• Session persistence — chat history in .rust-code/session_*.jsonl, resume with --resume
• Open-in-editor — jump to file:line in $EDITOR from any panel
• BigHead mode (--loop N) — autonomous task loop with circuit breaker, control file, and <solo:done/> signal
• Self-evolution (--evolve) — agent evaluates its own runs, patches code, rebuilds, and restarts

Background Tasks (tmux)

The agent can run long-lived commands (dev servers, watchers, builds) in named tmux windows via BashBgTool. Press F7 to see all running tasks with realtime log output. Ctrl+O to attach, Ctrl+K to kill.

Requires tmux installed (brew install tmux).

Skills

Skills are reusable agent instructions (markdown files) that teach the agent domain-specific workflows. Browse the skills.sh registry with F9, or from CLI:

rust-code skills search "deploy"
rust-code skills add tavily-ai/skills/web-search

Installed skills are injected into the agent context automatically.

MCP (Model Context Protocol)

Connect external tool servers by adding .mcp.json in your project or home directory:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

The agent discovers MCP tools at startup and can call them via McpToolCall.

Setup & Providers

On first launch, rust-code runs an interactive setup wizard to configure your preferred LLM backends and verifies authentication using rust-code doctor.

You can also run these manually:

rust-code setup
rust-code doctor

Supported providers include:

• Google AI via GEMINI_API_KEY
• Vertex AI via VERTEX_PROJECT (uses Google Cloud ADC or service account)
• Anthropic via ANTHROPIC_API_KEY
• OpenRouter via OPENROUTER_API_KEY
• Ollama (local via OLLAMA_HOST)

At least one provider must be configured before launching rust-code.

Examples:

export GEMINI_API_KEY="..."
rust-code

export GOOGLE_CLOUD_PROJECT="my-project"
rust-code

export OPENROUTER_API_KEY="..."
rust-code

Notes:

• Default: Gemini 3.1 Pro Preview with fallback to Flash and Flash Lite.
• Provider configuration: ~/.rust-code/config.toml or rust-code setup or rust-code config set.
• Vertex AI uses global region by default (not us-central1).

Quick Start

1. cd into the repository you want to work on.
2. Create an AGENTS.md file in that repo.
3. Export one provider credential.
4. Launch rust-code.
5. Start with a direct task like review this repo, fix the failing test, or add a new command.

AGENTS.md

rust-code works best when the target repository contains an AGENTS.md file with project-specific instructions.

Recommended contents:

• stack and framework versions
• architecture constraints
• code style rules
• test/build commands
• migration or release rules
• prompt or tool-schema rules
• file locations that must be edited first

Example:

# Agent Instructions

## Stack
- Rust 2024
- Tokio
- Ratatui

## Rules
- Prefer minimal patches
- Run `cargo check` after code changes
- Do not edit generated files directly
- Run `make check` before committing

## Commands
- Build: `cargo build`
- Check: `cargo check`
- Test: `cargo test`

The more concrete this file is, the better the agent performs.

Sessions and Local State

rust-code stores local state in .rust-code/:

• .rust-code/context/ for persistent agent guidance files
• .rust-code/session_*.jsonl for chat/session history

Use --resume to reopen the latest saved session:

rust-code --resume

TUI Shortcuts

Main shortcuts currently exposed by the UI:

• Enter: send message
• Ctrl+P: file search
• Ctrl+H: session history
• Ctrl+G: refresh git sidebar
• Tab: focus sidebar
• Ctrl+C: quit
• F1: diff channel
• F2: git history
• F3: files
• F4: sessions
• F5: refresh
• F6: symbols
• F7: background tasks
• F10: channels
• F12: quit

Inside side panels:

• Esc: close panel
• Ctrl+I: insert selected item into the prompt
• Ctrl+O: open or attach, where supported

Background tasks are backed by tmux, so having tmux installed is useful if you want long-running task inspection from the UI.

CLI

Usage: rust-code [COMMAND] [OPTIONS]

Commands:
  setup       Interactive provider setup wizard
  doctor      Check system deps and API auth (--fix to auto-install)
  skills      Manage agent skills (add, remove, search, list, catalog)
  sessions    List or search past chat sessions
  mcp         Show MCP server status and tools
  config      Set default provider (show, set, reset)
  task        Manage project tasks (list, show, create, done, update)

Options:
  -p, --prompt <PROMPT>    Run in headless mode with a prompt
  -r, --resume [TOPIC]     Resume last session or fuzzy-search by topic
  -s, --session <PATH>     Resume specific session file
      --cwd <PATH>         Working directory for headless mode
      --model <NAME>       Override model name
      --intent <MODE>      Intent mode: auto, ask, build, plan
      --sgr                Use SGR backend (pure Rust, no BAML)
      --local              Use local Ollama model
      --codex              Use ChatGPT Plus/Pro via Codex proxy
      --gemini-cli         Use Gemini CLI as LLM backend
      --loop <N>           Autonomous loop (BigHead mode)
      --max-hours <FLOAT>  Time limit for loop/evolve mode
      --evolve             Self-evolution mode
  -h, --help               Print help
  -V, --version            Print version

OpenAPI → Tool

Convert any REST API into a searchable, callable tool — no code generation needed.

# The agent can search and call APIs on the fly:
# "search github repos" → finds GET /search/repositories → calls it

• 10 popular APIs pre-configured: GitHub (1093 endpoints), Cloudflare (2656), Stripe, OpenAI, Supabase, PostHog, Slack, Linear, Vercel, Sentry
• APIs.guru fallback: 2800+ APIs searchable by name
• Auto-cache specs to ~/.sgr-agent/openapi-cache/
• TOML registry at ~/.sgr-agent/apis.toml for custom APIs
• Auto-detect auth from env vars (GITHUB_TOKEN, STRIPE_SECRET_KEY, etc.)
• Full $ref resolution, path-level parameter inheritance, YAML support

BigHead Mode (Autonomous Loop)

Run the agent in a loop for autonomous task execution:

rust-code -p "build a CLI tool for air quality" --loop 10 --max-hours 2

• Circuit breaker: stops after 3 consecutive identical failures
• Control file: .rust-code/loop-control (write stop, pause, skip)
• Signal: agent outputs <solo:done/> when task is complete
• Skills: --loop auto-loads skills/bighead/SKILL.md

Self-Evolution

The agent can evaluate and improve itself:

rust-code -p "improve your error handling" --evolve

• Evaluates each run: error rate, loop warnings, patch failures, steps
• Analyzes session history for recurring patterns
• Proposes and applies improvements to its own code
• Rebuilds and restarts via RESTART_AGENT signal
• Evolution log: .rust-code/evolution.jsonl

Development

The workspace consists of 5 crates:

Crate	What
rc-cli	Main binary — TUI, headless mode, 22 tools, agent loop
sgr-agent	LLM client + agent framework + session/memory/tools/providers/OpenAPI
sgr-agent-tui	Shared TUI shell — chat panel, fuzzy picker, focus system
solograph	MCP server for code intelligence
genai	Local fork of rust-genai — multi-provider LLM client

make build    # dev build
make test     # run all tests (450+ in sgr-agent alone)
make lint     # clippy on sgr-agent + sgr-agent-tui + solograph (-D warnings)
make check    # test + clippy + fmt (pre-commit gate)
make install  # build + strip + install to /usr/local/bin
make audit    # unused deps + large files audit
make help     # show all targets

Built With

What	Crate / Link
Agent architecture	Schema-Guided Reasoning (SGR) — typed tool dispatch via union types
LLM client	rust-genai (local fork) — multi-provider Rust client (Gemini, OpenAI, Anthropic, Ollama, etc.)
TUI framework	Ratatui + Crossterm
Text input	tui-textarea
Fuzzy search	Nucleo (from Helix editor)
Async runtime	Tokio
MCP client	rmcp — Rust SDK for Model Context Protocol
CLI	Clap
File traversal	ignore (from ripgrep, respects .gitignore)
Skills registry	skills.sh
Background tasks	tmux

Status

The crate is published on crates.io:

• https://crates.io/crates/rust-code

Release artifacts (Linux x86_64 + macOS aarch64) are published on GitHub when you push a tag matching v*.