Roko

Roko is a Rust toolkit for building agents that build themselves.

Point it at a codebase, describe what you want, and roko handles the rest: it composes prompts, dispatches LLM agents, verifies output with compilation and test gates, persists results as content-addressed signals, and learns from outcomes to get better over time. The core loop is observe, plan, execute, verify, learn, repeat.

18 crates. ~200K lines of Rust. 1,600+ tests.

Quick start

cargo install --path crates/roko-cli
roko init my-project && cd my-project
roko run "add a health check endpoint to the API"

roko init detects your project type, sets up gates (cargo check for Rust, tsc for TypeScript, go build for Go), and writes a working roko.toml. roko run does everything else.

How it works

One-shot execution

The fastest path. One command, full pipeline.

roko run "refactor the auth module to use JWT"

Roko composes a prompt from your codebase context, calls the configured LLM agent, runs the output through compile/test/lint gates, and persists the result as a signal. If gates fail, it retries with escalating models.

Full planning pipeline

For larger work that spans multiple tasks.

# 1. Capture what you want to build
roko prd idea "Add user authentication with OAuth2"

# 2. Research the topic (optional -- uses Perplexity for web-grounded citations)
roko research topic "OAuth2 best practices in Rust"

# 3. Generate a detailed PRD (agent-assisted)
roko prd draft new "oauth2-auth"

# 4. Create an implementation plan with tasks
roko prd plan oauth2-auth

# 5. Execute the plan (agents work in parallel, gates verify each task, state persists)
roko plan run plans/

# 6. Resume if interrupted
roko plan run plans/ --resume-plan

# 7. Watch progress
roko dashboard

Each task in the plan runs through its own agent loop with independent gate verification. Failed tasks feed back into the planner for re-decomposition.

Implicit prompt mode

If no subcommand matches, roko treats the argument as a prompt:

roko "fix the bug in auth.rs"

This is equivalent to roko run "fix the bug in auth.rs". The shortest path from thought to execution.

Dashboard

roko dashboard launches an interactive terminal UI built on ratatui with the rosedust color theme. Seven tabs, accessible via F1-F7:

Additional keybindings: q to quit, ? for help, Tab/Shift+Tab to cycle panels, Enter to drill into a task, i to inject a signal into a running session.

When idle, the dashboard shows recent episodes, gate results, system health, and config summary rather than blank panels.

Multi-provider support

Roko routes work across LLM providers based on task complexity, cost, and latency. Supported backends:

Tier-based model routing assigns the cheapest viable model to each task:

[agent.tier_models]
mechanical = "gemini-2-5-flash-lite"   # imports, renames, trivial edits
focused = "gemini-2-5-flash"           # single functions, tests
integrative = "claude-sonnet-4-6"      # multi-module wiring
architectural = "claude-opus-4-6"      # API design, architecture

On failure, roko escalates to the next tier's model automatically.

See examples/ for complete provider configurations:

• roko-gemini.toml -- Gemini-only with 8 model tiers
• roko-multi-provider.toml -- Claude + Gemini + Perplexity routing
• roko-perplexity.toml -- Research-focused with deep research

Architecture

One noun, six verbs

Everything in roko is a Signal -- a content-addressed (BLAKE3), timestamped, scored record of something that happened. Signals form a DAG through parent pointers, so you can always trace why the agent made a decision by walking backwards through lineage.

Six traits define what you can do with signals:

Universal loop

Every agent runs the same loop:

query -> score -> route -> compose -> act -> verify -> write -> react

Stop at any step and you still have something useful. A prompt composer without an agent is a retrieval pipeline. An agent without gates is a raw LLM wrapper. The pieces are independent.

Crate map

Gate pipeline

Every agent output passes through a gate pipeline before it is accepted. Gates run sequentially and short-circuit on the first failure by default.

Rungs

The pipeline uses a 7-rung system. Which rungs execute depends on task complexity -- trivial tasks skip expensive checks, complex tasks run all of them.

Additional specialized gates: DiffGate (patch analysis), LlmJudge (subjective quality), FactCheck (search-backed verification), CodeExec (sandboxed execution).

Adaptive thresholds

Gate thresholds adjust over time using exponential moving averages. If a gate consistently passes, its threshold tightens. If it consistently fails, the threshold relaxes. Thresholds persist to .roko/learn/gate-thresholds.json.

Learning and self-improvement

Roko tracks its own performance and gets better with use.

Cascade router

Three-stage model selection: static tier mapping, learned bandit weights, and provider health. The router picks the cheapest model that can handle the task, based on historical success rates.

roko model route claude-sonnet-4-6 --explain --complexity focused

Prompt experiments

A/B test different prompt strategies. The experiment store tracks success rates per variant and promotes winners automatically.

roko experiment list
roko experiment show <id>

Efficiency tracking

Every agent turn records tokens in/out, latency, cost, and gate pass/fail. These events feed the cascade router, the dashboard, and the dream cycle.

Knowledge distillation (neuro)

Completed episodes are distilled into durable knowledge entries: facts, insights, heuristics, procedures, constraints, and anti-knowledge. Knowledge decays over time with configurable half-lives (365 days for facts, 30 days for insights, 90 days for heuristics).

roko neuro query "authentication patterns"
roko neuro stats

Dream cycle

Offline consolidation that runs between work sessions. The dream engine batches completed episodes, clusters them by task shape, distills knowledge, and promotes reliable success patterns into playbooks.

roko dream run
roko dream report
roko dream schedule

Deployment

HTTP control plane (roko serve)

roko serve                           # default bind 127.0.0.1:6677
roko serve --bind 0.0.0.0 --port 9090

Starts an Axum-based HTTP server with ~85 routes grouped by subsystem:

Example responses:

curl http://localhost:6677/api/health
# {"status":"ok","version":"0.1.0","uptime_seconds":123}

curl http://localhost:6677/api/metrics/c_factor
# {"overall":0.73,"components":{...},"episode_count":120}

curl http://localhost:6677/api/learn/efficiency
# {"total_cost":12.45,"cost_per_task":0.83,"tokens_per_task":24500.0,...}

curl http://localhost:6677/api/agents?owner=will
# [{"agent_id":"nunchi-intelligence","owner":"will","endpoints":{...}}]

Per-agent sidecar (roko-agent-server)

Each registered agent also runs its own small HTTP server (typically on a private port, proxied by the control plane):

POST /message wire shape:

curl -X POST http://localhost:6677/api/agents/nunchi-intelligence/message \
  -H "Content-Type: application/json" \
  -d '{"prompt":"ping"}'
# {"response":"Hello, world","reasoning":null,"usage":{...},"session":{...},
#  "finish_reason":"stop","engram_id":"engram-...","context":{...}}

Missing dispatcher returns 503. Backend failure returns 502. See crates/roko-agent-server/README.md for the full contract.

Chat with a running agent

roko chat --agent nunchi-intelligence
roko chat --agent nunchi-intelligence --serve-url http://localhost:6677

Opens an interactive REPL that POSTs to the sidecar through the aggregator. Useful for ad-hoc debugging, prompt iteration, and smoke-testing a deployed agent from your terminal.

Background daemon

roko daemon start --port 9090    # start in background
roko daemon status               # check if running
roko daemon logs -f              # tail logs
roko daemon stop                 # graceful shutdown
roko daemon install              # install as macOS launchd service

The daemon watches for file changes, processes cron-scheduled tasks, ingests webhooks, and dispatches agents from event subscriptions.

Cloud worker

roko worker --port 8080

Reads a template from environment variables and serves tasks. Designed for Railway, Fly.io, and container platforms.

Cloud deployment

roko deploy railway    # deploy via Railway GraphQL API
roko deploy fly        # generate fly.toml and deploy
roko deploy docker     # build and tag Docker image

Configuration

Roko uses layered TOML configuration: global (~/.config/roko/config.toml) merged with project (./roko.toml), with environment variables as overrides.

Minimal config

[agent]
command = "claude"
model = "claude-sonnet-4-6"

[[gate]]
kind = "compile"

[[gate]]
kind = "test"

[budget]
max_plan_usd = 10.0
max_task_usd = 1.0

Full project config

[agent]
command = "claude"
args = ["--print", "--output-format", "stream-json"]
model = "claude-sonnet-4-6"
effort = "high"
bare_mode = true
fallback_model = "claude-haiku-4-5"
timeout_ms = 300000

[agent.tier_models]
mechanical = "claude-haiku-4-5"
focused = "claude-sonnet-4-6"
integrative = "claude-sonnet-4-6"
architectural = "claude-opus-4-6"

[agent.escalation]
max_retries = 3
escalate_model = true

[prompt]
token_budget = 50000
role = "You are a Roko agent working on the project."

[budget]
max_plan_usd = 10.0
max_task_usd = 1.0
warn_at_percent = 80

[[gate]]
kind = "compile"

[[gate]]
kind = "test"

Config management

roko config init                            # interactive wizard
roko config show                            # effective merged config
roko config set agent.model claude-opus-4-6 # set a value
roko config validate                        # check syntax and references
roko config migrate                         # upgrade legacy format

CLI quick reference

Full reference with all 85+ commands, flags, and examples: docs/CLI-REFERENCE.md

Building and testing

rustup update stable          # 1.91+ required for alloy deps
cargo build --workspace
cargo test --workspace
cargo clippy --workspace --no-deps -- -D warnings

Running a single crate

cargo test -p roko-core
cargo test -p roko-agent
cargo test -p roko-gate

Contributing

Contributions are welcome. A few ground rules:

1. Search before writing. This codebase has 18 crates and 200K lines. The thing you want to build might already exist. Run grep -rn 'StructName' crates/ --include='*.rs' first.
2. Wire, don't build. The most common pattern in this repo is "built but never connected." Before adding new code, check if existing code needs to be called from the runtime.
3. Verify before marking done. Run the actual CLI code path. Passing unit tests does not mean the feature works end-to-end.
4. All tests must pass. cargo test --workspace and cargo clippy --workspace --no-deps -- -D warnings must both be clean.

License

MIT OR Apache-2.0 (dual-licensed).