AI coding agent for your terminal — built for developers, not teams or enterprises (yet).
Quick Start · Features · Usage · Skills · Tools · Architecture · Benchmarks · Contributing
rho is an AI-powered coding agent that lives in your terminal. It reads your codebase, writes and edits files, runs tests, and manages git — all through natural language. Unlike IDE-bound tools, rho works over SSH and on any machine with a shell.
Developer path: one machine, keychain credentials, local memory. Run rho path to check readiness.
- Model-agnostic — supports many first-class providers through flux (the exact count is dynamic — see
rho --help), including Anthropic, OpenAI, Gemini, Fireworks AI, Concentrate AI (pay-as-you-go), DeepSeek, and Ollama - Zero CGO — single static binary, cross-compiled for linux/darwin/windows on amd64/arm64
- Privacy-first — your code never leaves your machine except to the LLM API you choose
- Runs anywhere — host execution on any machine with a shell, including over SSH
- Extensible — 40+ built-in tools, MCP server support, community skill registry
Rho is in active development. Contributor source builds are the primary path today while we keep hardening the product in the open. Tagged releases and install assets may exist for validation, but they are not the recommended first path yet.
Follow GrayCode for progress. When Rho is ready to try, we will announce it on graycodeai.com.
Pick one — all install the same rho binary (versioned into ~/.rho/bin, symlinked as rho):
# 1. Script (any shell, verifies checksum; cosign signature when available)
curl -fsSL https://raw.githubusercontent.com/GrayCodeAI/rho/main/install.sh | sh
# 2. Homebrew (macOS / Linuxbrew) — after the next tagged release
brew install graycodeai/tap/rho
# 3. npm (wraps the same release binaries)
npm install -g @graycodeai/rhoIf ~/.rho/bin is not on your PATH, add it to your shell profile.
Then:
rho # interactive REPL (/config on first run: API key + model)
rho path # verify readinessgit clone https://github.com/GrayCodeAI/rho && cd rho
make setup # generates go.work referencing sibling support repos in the graycode-eco workspace
go build -o rho ./cmd/rho
./rho
# First run — paste API key in /config (stored in macOS Keychain / Linux keyring)
# Verify readiness
./rho pathNo Docker or container runtime is required. Rho executes agent commands
directly on the host. Run rho path (or rho doctor) to see an onboarding
checklist: credentials → model → catalog → ecosystem.
See docs/SECURITY-DEVELOPER.md for the credential model.
Do not put API keys in shell env or .env for rho.
Optional for contributors:
go install github.com/GrayCodeAI/rho/cmd/rho@latestBuilt with Bubble Tea for a smooth, keyboard-driven experience with vim-style keybindings.
| Category | Tools |
|---|---|
| Files | Read, Write, Edit, LS, Glob, Grep |
| Shell | Bash, PowerShell, CronCreate, CronDelete |
| Git | GitCommit, SmartCommit, EnterWorktree, ExitWorktree |
| Web | WebFetch, WebSearch, CodeSearch |
| Tasks | TodoWrite, TaskCreate, TaskList, TaskUpdate |
| Code | LSP diagnostics, CodeSearch, NotebookEdit, SQL (read-only DB exploration) |
| MCP | ListMcpResources, ReadMcpResource |
Export the latest or a selected Rho session as validated graph nodes, edges, and lifecycle events:
rho graph export
rho graph export <session-id>
rho graph export --mission-dir /path/to/mission
# Explicitly privacy-normalize and sync the graph for a connected cloud project
rho cloud graph sync <session-id>
rho cloud graph sync --mission-dir /path/to/missionCloud commands require an endpoint. There is no default: pass --endpoint or
set RHO_CLOUD_URL to your Rho Cloud worker URL before running
rho cloud login. https://api.graycodeai.com is the browser BFF and
will reject a device token.
The export contains metadata and hashes, not prompts, tool arguments/results,
policy reasons, verification evidence, or runtime output. Persisted chat
sessions automatically append privacy-safe permission, enabled approval-gate,
and VerifyPlanExecution summaries for subsequent graph exports. Mission runs
also persist a portable mission-graph.json; the mission form is validated and
synchronized explicitly with the --mission-dir variants above.
For larger tasks, decompose work into parallel feature branches (power-user / future team workflows):
rho mission "Add auth, rate limiting, and logging"Each sub-agent runs in its own git worktree with full autonomy.
Discover and install modular instruction packages for specialized workflows:
rho skills search api # Search community registry
rho skills install go-review # Install from GitHub
rho skills audit # Security scan installed skillsrho exposes two independent chat command centers — trust tier and the spec-driven workflow gate — rather than one merged permission mode:
/autonomy
/autonomy tier <scout|builder|operator|autonomous>
/autonomy dry-run <on|off>
/autonomy allow <rule>
/autonomy deny <rule>
/autonomy rules
/autonomy reset
/autonomy save [project|global]
/spec
/spec [what to build]
/spec status
/spec reset
The model is:
Tiercontrols autonomy (bare/autonomyopens a picker for this):Always Ask— prompts for permission on every tool callScoutBuilderOperatorAutonomous
Dry-runis a kill switch: denies every tool call unconditionally, regardless of tier or spec stage.Rulescontrol explicit allow/deny exceptions.Specis a separate, independent workflow gate (bare/specopens a picker): starting it walks the model throughSpecify → Plan → Tasks, writing real files to.rho/specs/<slug>/, and blocks Write/Edit/Bash until you approve moving to implementation — at any trust tier, including Autonomous.
/autonomy and /spec are the main control surfaces for normal chat usage.
Older merged permission-mode chat commands have been removed in favor of
these two independent flows.
Connect external tools via Model Context Protocol and get code intelligence through Language Server Protocol. MCP also supports a WebSocket transport (opt-in) in addition to stdio/HTTP.
rho --watch watches your tree for AI! (do it now) and AI? (answer my question) comments and acts on them automatically — leave a directive in code, save, and rho responds. Off by default; enabled via the --watch flag.
A bundled GitHub Action (.github/actions/rho) runs rho in your pipeline: interactive mode on @rho mentions in issue/PR comments, automation mode on labeled issues/PRs, and skill dispatch when a prompt begins with / (e.g. /code-review).
The daemon exposes Telegram, Discord, and Slack gateways so you can chat with rho from your messaging app. Disabled by default; enabled per-channel via daemon config.
An AST-based repository map (internal/context/repomap) gives the model a structural overview of your code. On first run, rho can auto-analyze the codebase to seed context (default-off, opt-in).
After edits, rho can run the matching linter and iterate on fixes (bounded retries) before handing back. Opt-in; preserves existing behavior when disabled.
Feed screenshots and images into the conversation for vision-capable models (internal/engine/vision.go).
Read-only sub-agent modes: plan decomposes a task into steps, explore investigates the codebase with a configurable thoroughness budget (quick / medium / very-thorough).
SmartCommit and the diff summarizer generate Conventional Commit messages from your staged changes.
LangGraph-style durable workflows with named, resumable step checkpoints and optional human-in-the-loop approval gates that persist the gate decision.
Request JSON-Schema-constrained responses; results are validated against the schema and retried once on mismatch.
Define personas and eval tasks in YAML (in addition to markdown personas), including per-agent display color and lifecycle hooks.
An optional, non-excludable org-policy rule tier (highest precedence) with HTML-comment stripping of rule files for IT-managed deployments.
Features adopted from open-source agent projects. All are off by default unless explicitly enabled; see each section for details.
| Feature | Flag / Command | What it does |
|---|---|---|
| Best-of-N fan-out | rho exec --fanout N |
Run the same prompt in N isolated worktrees, compare, merge winner |
| Completion notifications | RHO_NOTIFY_WEBHOOK_URL / RHO_NOTIFY_TELEGRAM_TOKEN + _CHAT_ID |
Webhook or Telegram ping when a run finishes |
| Incremental system-context | RHO_INCREMENTAL_CONTEXT=1 |
Reconcile dynamic sections instead of rebuilding the prompt |
| Tool-catalog shrink | RHO_TOOL_SHRINK=1 |
Compress the tool catalog sent on every request |
| Compaction segments | RHO_COMPACTION_SEGMENT_DETAIL=verbose|balanced|minimal|none |
Persist verbatim compacted turns to disk |
| Skill curator | rho skills curator status/run/pin/unpin/archive + RHO_SKILL_CURATOR=1 |
Auto-archive cold agent-created skills (recoverable) |
| Structural code match | CodeMatch tool |
Tree-sitter query search over Go/Python/TS/TSX |
| Composable toolsets | rho toolset [name] + Toolset tool |
Named tool groups (research, dev, ops, full_stack) |
| App verification | AppVerify tool |
Boot-smoke check with readiness polling and evidence artifacts |
| Media generation | GenerateMedia tool |
Image/video generation with local persistence. Backend via tool.SetMediaEngine; an OpenAI-compatible client ships in flux/client (ImageClient), wired by the host (boundary-guarded — rho routes through the flux facade) |
| Voice transcription | Telegram voice notes + stt package |
Transcribe Telegram voice/audio into the prompt. Backend via stt.SetTranscriber; an OpenAI-compatible client ships in flux/client (AudioClient), wired by the host |
| Bounded autonomous budgets | internal/engine (AutonomousBudget) |
Track turns/tokens/time/continuations; report why a run stopped (budget vs gate-passed vs error) |
| Agent family messaging | internal/multiagent (FamilyMessenger) |
Direct parent/sibling/child messages with pending caps + rate limits |
| Path reservations | internal/multiagent ledger |
Detect overlapping-file changes between parallel branches |
| Live agent status | GET /v1/agent/status (daemon) |
Machine-readable working/idle/stale per session |
| X/Twitter search | SearchX tool |
Live X search by forwarding a query to an xAI endpoint with server-side search; returns a cited summary. Requires XAI_API_KEY (or GROK_API_KEY) |
| Desktop computer-use | ComputerUse tool |
snapshot/click/type/scroll/press/screenshot via a pluggable tool.SetComputerBackend seam (host wires a native macOS accessibility backend) |
| Token-cheaper file views | Read tool --minify |
Read-only, comment-stripped, whitespace-dense file view (Go via go/parser; other languages string-aware; never touches disk) — fewer tokens per read |
| Classified provider hints | internal/errhint |
Buckets provider errors (Auth/RateLimit/Connectivity/ModelNotFound/ContextOverflow) into a one-line fixable next step. Wired into TUI error rows (friendlyErrorMessage) and rho exec CLI errors |
| Atomic install transactions | internal/installtxn |
Cross-process staged install/remove with rollback. Wired into skill install (atomic SKILL.md publish) |
| Test command discovery | internal/testrunner |
Auto-detect test/verify commands (Go/npm/bun/pnpm/yarn/pytest/cargo) and parse runner output into structured results. Wired into rho verify |
| Circuit breaker | internal/circuitbreaker |
Closed/open/half-open retry-storm protection with cooldown. Wired into auto-compaction (cooldown + half-open auto-retry) |
| Smart turn routing | internal/smartrouting |
Deterministic simple/strong turn classifier with fail-toward-strong safety. Wired into per-turn model selection (settings.smart_routing) |
| Conversation arc | internal/conversationarc |
Durable sidecar memory of goals/decisions/milestones/phase with a byte-stable summary. Wired into sessions (loaded on open, saved on close, injected into the system prompt) |
| Relevance pruning | internal/relevanceprune |
Token-budgeted context pruning preserving recent turns/tool calls/errors. Wired into compaction as a relevance strategy |
| Tool-result clearing | internal/engine (ClearOldToolResults) |
Two-tier context management: at 80% of the context window, stale tool-result content is replaced with [output cleared] placeholders (tool_use kept intact) before compacting — a gentler tier below compaction |
| Approval pause timing | internal/permissions |
Approval requests record decision timestamp + human deliberation duration (DecisionAt/PauseDuration) for approval-latency observability |
| Graceful exhaustion | internal/engine (SynthesisForExhaustion) |
When turn/token/time limits hit, one final tools-disabled LLM call synthesizes a coherent completion (accomplished/remaining/next steps) instead of a bare stop line. Opt-in via RHO_GRACEFUL_EXHAUSTION=1 |
| Deterministic replay cache | internal/replaycache (RHO_REPLAY_CACHE_DIR) |
Disk-persisted SHA-256-keyed cache of completions; identical requests replay stored responses for reproducible regression runs |
rho # Start REPL
rho -r abc123 # Resume session
rho -c # Continue latest session
rho --provider openai --model gpt-4o # Override provider# Inside the TUI
/autonomy
/autonomy tier builder
/autonomy allow Bash(git:*)
/autonomy deny Bash(rm -rf *)
/autonomy save project
/spec add dark mode supportrho -p "explain this repo" # Print response, exit
rho -p "fix tests" --allowed-tools "Bash(go test:*) Edit Read"
rho exec "refactor auth module" # Full engine, non-interactive
rho exec --auto full "add error handling" # Full autonomy
rho exec --worktree "add rate limiting" # Isolated branch
rho exec --agent reviewer "review last commit" # Custom personarho path # Developer path readiness (setup + security)
rho doctor # Full health report (flux + token pipeline panel)
rho ecosystem # Ecosystem panel only
rho preflight # Quick ready-to-chat check
make path # Developer path verification
make smoke # Build + quick verification scriptSee docs/SECURITY-DEVELOPER.md.
See docs/ecosystem-message-flow.md for how flux connects during a chat session, and docs/ECOSYSTEM-WIRING.md for the current-to-proposed architecture and repository boundaries.
In the TUI: /path, /ecosystem, /memory (AGENTS.md).
rho daemon start # Background HTTP server on port 4590
rho daemon status # Check if running
rho daemon stop # Graceful shutdownEndpoints: GET /v1/health, GET /v1/ready (dependency-aware readiness), POST /v1/chat (JSON or SSE streaming)
rho mission "Add auth, rate limiting, and logging"
rho mission --workers 6 "Refactor into microservices"
rho mission --dry-run "What would this decompose into?"
rho mission --from-tasks # Execute validated dependency wavesrho works with any LLM provider. Developer path: paste keys in /config (stored in OS keychain) — not shell env or .env. Use rho credentials status to verify.
| Provider | ID | Key (via /config) |
|---|---|---|
| Anthropic | anthropic |
ANTHROPIC_API_KEY |
| OpenAI | openai |
OPENAI_API_KEY |
| Google Gemini | gemini |
GEMINI_API_KEY |
| OpenRouter | openrouter |
OPENROUTER_API_KEY |
| Fireworks AI | fireworks |
FIREWORKS_API_KEY |
| xAI (Grok) | grok |
XAI_API_KEY |
| Z.AI | z-ai |
ZAI_API_KEY |
| CanopyWave | canopywave |
CANOPYWAVE_API_KEY |
| OpenCode Go | opencodego |
OPENCODEGO_API_KEY |
| Kimi (Moonshot) | kimi |
MOONSHOT_API_KEY |
| Xiaomi (MiMo) Pay-as-you-go | xiaomi_mimo_payg |
XIAOMI_MIMO_PAYG_API_KEY |
| Xiaomi (MiMo) Token Plan | xiaomi_mimo_token_plan |
XIAOMI_MIMO_TOKEN_PLAN_API_KEY (pick region in /config) |
| Ollama (local) | ollama |
OLLAMA_BASE_URL (no API key) |
Provider routing, model resolution, and retries are handled by flux.
For deployment-aware routing, set "deployment_routing": true in .rho/settings.json
or export RHO_DEPLOYMENT_ROUTING=true. Rho will route canonical model IDs through
Flux's deployment catalog, so new models can be exposed by refreshing the catalog
instead of changing Rho. In chat, run /refresh-model-catalog to fetch the latest
deployment-aware catalog into ~/.flux/model_catalog.json.
rho is built in Go with a modular, layered architecture:
rho/
├── bin/ # Built binaries (rho, rho_bin)
├── cmd/ # CLI entry point (Cobra + Bubble Tea TUI)
├── internal/
│ ├── engine/ # Agent loop, compaction, self-improvement
│ │ └── lifecycle/ # Self-improvement loop, limits tracking
│ ├── tool/ # 40+ built-in tools with safety layer
│ │ └── codegen_builtins.go # Code generation templates
│ ├── config/ # Settings, budget tracking, agent personas
│ ├── session/ # Persistence (JSONL, WAL, checkpoints)
│ ├── api/ # HTTP API server
│ ├── daemon/ # Background HTTP/SSE server
│ ├── token/ # Token counting, compression, usage, secrets
│ ├── permissions/ # User approval system with auto-learning
│ ├── hooks/ # Event-driven plugin system
│ ├── mcp/ # Model Context Protocol client
│ ├── intelligence/ # Code intelligence (repomap, memory, planner)
│ ├── multiagent/ # Mission orchestration, parallel execution
│ ├── observability/ # Analytics, metrics, logging, tracing
│ ├── resilience/ # Circuit breaker, rate limiting, retries
│ ├── feature/ # eval, fingerprint, voice, IDE integration
│ ├── bridge/ # External bridges (sessioncapture)
│ ├── provider/ # Provider routing
│ └── system/ # Bus, cron, retention, shutdown
├── docs/ # Architecture, security, integration docs
└── testdata/ # Test fixtures
Ecosystem sibling repos (independent Git repos in the `graycode-eco` parent
folder):
├── flux/ # LLM provider runtime
rho is the main CLI/product and integrates these GrayCodeAI repositories in three runtime layers plus optional tooling/platform services:
- Primary product: rho is the only end-user product surface in this ecosystem.
- Provider engine mounted by Rho: flux is the LLM provider runtime, consumed through its stable engine facade.
- API consumers/extensions: graycode-skills provides Rho skills
installed on demand (
rho skills install). - Tooling/platform: graycode-platform contains the optional web/BFF/Rho Cloud plane and is outside the Rho Go runtime graph.
Local development uses:
go.modmodules: pinned requirements forflux- Workspace +
go.work: sibling support repos are cloned in thegraycode-ecoworkspace (as../<repo>);go.workresolves the module paths to those local checkouts - Module-mode builds: standalone builds resolve the pinned
go.modversions from the module proxy (no workspace)
Cross-repo contracts now live in internal/contracts (vendored from the
removed github.com/GrayCodeAI/eagle module) so support repos do not depend
on Rho internals. External consumers should vendor the needed DTOs from internal/contracts
until a published contracts module exists.
Current contract packages (internal/contracts/):
types— severity, findingsgraph— portable graph vocabulary: nodes, edges, events, provenanceagent— typed subagent spawn DTOs and hook eventspolicy— permission and policy verdict contractscontracts/review— normalized review findings, comments, stats, resultscontracts/verify— normalized verification findings, stats, reportsevents— tool, trace, and usage eventsharness— harness evaluation reports and dimension scores
You may keep a personal parent go.work that lists alternate clones on disk for multi-repo development.
| Component | Repository | Purpose |
|---|---|---|
| rho | This repo | AI coding agent |
| flux | GrayCodeAI/flux | LLM provider runtime |
| graycode-skills | GrayCodeAI/graycode-skills | Community skill registry |
| graycode-platform | GrayCodeAI/graycode-platform | Web, BFF, and Rho Cloud |
ecosystem.yaml is the canonical inventory of repositories cloned as
siblings in this local workspace; tooling reads it rather than carrying its
own repo-name list. flux is the only Go module dependency outside this
repo; it is consumed through its stable engine facade.
For the consolidated repo map and the current-vs-proposed architecture diagrams, see docs/architecture/rho-current-vs-proposed.md. For execution-graph ownership, automatic capture seams, and export/sync commands, see docs/architecture/execution-graph.md.
- Go 1.26+
go build ./cmd/rho # Build binary
go test -race ./... # Run all tests with race detector
make ci # Run full CI suite (lint, test, security)
make cover # Generate coverage reportPublished, reproducible CPU benchmarks (session save/load, repo-map size/tokens)
live in docs/BENCHMARKS.md, recorded with machine + commit so
numbers are comparable across runs. Reproduce with the existing go test -bench
targets there; nothing gates releases on them.
Headline numbers (Go 1.26.6, AMD EPYC 7543P, go test -bench -benchmem -count=3):
| Benchmark | Result |
|---|---|
| Session save (1000 msgs) | ~790 µs, 256 KB, 2,056 allocs |
| Session load (1000 msgs) | ~5.3 ms |
| Repo-map generate (100-file tree, 2,500 symbols) | ~2.2 ms, ~21.6k est. tokens, ~364 KB |
| Session save (100 msgs) | ~183 µs, 32 KB, 256 allocs |
rho follows Go conventions: cmd/ for entry points, internal/ for private code, tests alongside source files. See docs/architecture.md for details.
We welcome contributions! Please see CONTRIBUTING.md for development setup, commit conventions, and the PR process.
Quick start:
- Fork and create a branch:
git checkout -b feat/short-description - Make changes in small, focused commits
- Run
make cilocally - Open a pull request
Use Conventional Commits for commit messages — release-please uses them for versioning.
MIT — see LICENSE for details.
© 2026 GrayCode AI