AI Coding Agent for Your Terminal

AI coding agent for your terminal — built for developers, not teams or enterprises (yet).

Quick Start · Features · Usage · Skills · Tools · Architecture · Benchmarks · Contributing

Why rho

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

Status

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.

Install

Prebuilt installs are available from v0.3.0, the first release published under the rho name. Until v0.3.0 appears on the releases page, build from source (see Quick Start). The older v0.1.0–v0.2.0 tags predate the rename: they ship hawk_* archives under the old module path and cannot be installed as rho.

From v0.3.0:

# Script: installs ~/.rho/bin/rho-<version> and links it as ~/.rho/bin/rho.
# Always checks the archive's SHA-256 against checksums.txt; also verifies the
# cosign signature of checksums.txt when cosign is installed (it says so when
# it is not). Set RHO_REQUIRE_COSIGN=1 to refuse installing without cosign.
curl -fsSL https://raw.githubusercontent.com/GrayCodeAI/rho/v0.3.0/install.sh | sh

# Pin a version or choose the install prefix (see: sh install.sh --help)
curl -fsSL https://raw.githubusercontent.com/GrayCodeAI/rho/v0.3.0/install.sh | sh -s -- --version 0.3.0 --prefix "$HOME/.rho"

# Go toolchain (Go 1.26+): builds the tagged module from source
go install github.com/GrayCodeAI/rho/cmd/rho@latest

Each release carries rho_<version>_<os>_<arch> archives for linux/darwin/windows on amd64/arm64, checksums.txt, its cosign signature bundle checksums.txt.sigstore.json, and SPDX SBOMs; the release notes show how to verify them by hand. Homebrew and npm packages are not available: there is no graycodeai/tap tap and nothing is published under @graycodeai on npm.

If ~/.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 readiness

Quick Start (contributors — from source)

git 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 path

No 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: install the current main with the Go toolchain. Use @main until v0.3.0 is tagged: @latest still resolves to the hawk-era v0.2.0, which does not contain cmd/rho.

go install github.com/GrayCodeAI/rho/cmd/rho@main

Features

Interactive Terminal UI

Built with Bubble Tea for a smooth, keyboard-driven experience with vim-style keybindings.

40+ Built-in Tools

Portable Execution Graph

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/mission

Syncing needs a GrayCode Cloud connection.

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.

GrayCode Cloud (optional)

GrayCode Cloud is the optional, opt-in hosted control plane for device login, usage, delivery context and graph sync. Rho works fully without it and sends nothing until you connect. It is alpha and still being rolled out: if rho cloud login cannot reach cloud.graycodeai.com, the hosted service is not available to you yet, and nothing else in Rho is affected.

rho cloud login                     # browser device login
rho cloud status                    # endpoint, device, project, token storage
rho cloud context                   # sync repository, branch, CI and deployment context
rho cloud graph sync <session-id>   # upload a privacy-normalized execution graph

• Endpoint. New connections use https://cloud.graycodeai.com unless you pass --endpoint or set RHO_CLOUD_URL (for example a local Worker at http://127.0.0.1:8787). Only https:// is accepted, except plain http:// on localhost, 127.0.0.1 and [::1]. A saved connection keeps the endpoint that issued its token. https://api.graycodeai.com is the browser API and rejects device tokens.
• What is sent. Once connected, each rho exec run reports one usage event (model, token counts, duration, status). This is fail-open: it never changes the run's result, and rho waits at most 3 seconds for it after the output is written. rho cloud context and rho cloud graph sync are explicit, and any rejection is reported as an error.
• Device token. rho keeps the token in the macOS Keychain or the Windows Credential Manager. Linux and other platforms have no credential-store integration yet, so the token is written to .tokens in the Rho config directory (~/.config/rho/.tokens by default, or $RHO_CONFIG_DIR/.tokens) as plaintext with mode 0600. rho cloud login/connect print a warning when that happens and rho cloud status shows where the token lives.
• Manual connection. rho cloud connect --device-id <id> --project-id <id> --token-stdin < token.txt saves an existing device; without --token-stdin it prompts for the token without echo. --token <value> still works but is deprecated because it exposes the token in shell history and ps.

Multi-Agent Mission Mode (optional)

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.

Community Skills

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 skills

Permission Center

rho 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:

• Tier controls autonomy (bare /autonomy opens a picker for this):
  • Always Ask — prompts for permission on every tool call
  • Scout
  • Builder
  • Operator
  • Autonomous
• Dry-run is a kill switch: denies every tool call unconditionally, regardless of tier or spec stage.
• Rules control explicit allow/deny exceptions.
• Spec is a separate, independent workflow gate (bare /spec opens a picker): starting it walks the model through Specify → 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.

MCP & LSP Support

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.

Watch Mode (AI-comment loop)

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.

CI / GitHub Action

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).

Messaging Gateways (opt-in)

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.

AST Repo-Map & Codebase Analysis

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).

Auto-Lint / Auto-Fix Cycle

After edits, rho can run the matching linter and iterate on fixes (bounded retries) before handing back. Opt-in; preserves existing behavior when disabled.

Image / Multimodal Context

Feed screenshots and images into the conversation for vision-capable models (internal/engine/vision.go).

Plan & Explore Sub-Agents

Read-only sub-agent modes: plan decomposes a task into steps, explore investigates the codebase with a configurable thoroughness budget (quick / medium / very-thorough).

Conventional-Commit Generation

SmartCommit and the diff summarizer generate Conventional Commit messages from your staged changes.

Durable Workflows & Approval Gates

LangGraph-style durable workflows with named, resumable step checkpoints and optional human-in-the-loop approval gates that persist the gate decision.

Structured Output

Request JSON-Schema-constrained responses; results are validated against the schema and retried once on mismatch.

YAML Agents & Tasks

Define personas and eval tasks in YAML (in addition to markdown personas), including per-agent display color and lifecycle hooks.

IT-Managed Policy Tier

An optional, non-excludable org-policy rule tier (highest precedence) with HTML-comment stripping of rule files for IT-managed deployments.

Adopted Capabilities (env-gated)

Features adopted from open-source agent projects. All are off by default unless explicitly enabled; see each section for details.

Usage

Interactive Mode

rho                              # Start REPL
rho -r abc123                    # Resume session
rho -c                           # Continue latest session
rho --provider openai --model gpt-4o  # Override provider

Permission Examples

# Inside the TUI
/autonomy
/autonomy tier builder
/autonomy allow Bash(git:*)
/autonomy deny Bash(rm -rf *)
/autonomy save project

/spec add dark mode support

Non-Interactive Mode

rho -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 persona

Diagnostics & ecosystem

rho 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 script

See 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).

Daemon Mode

rho daemon start              # Background HTTP server on port 4590
rho daemon status             # Check if running
rho daemon stop               # Graceful shutdown

Endpoints: GET /v1/health, GET /v1/ready (dependency-aware readiness), POST /v1/chat (JSON or SSE streaming)

Mission Mode

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 waves

Providers

rho 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 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.

Architecture

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

Ecosystem

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.mod modules: pinned requirements for flux
• Workspace + go.work: sibling support repos are cloned in the graycode-eco workspace (as ../<repo>); go.work resolves the module paths to those local checkouts
• Module-mode builds: standalone builds resolve the pinned go.mod versions 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, findings
• graph — portable graph vocabulary: nodes, edges, events, provenance
• agent — typed subagent spawn DTOs and hook events
• policy — permission and policy verdict contracts
• contracts/review — normalized review findings, comments, stats, results
• contracts/verify — normalized verification findings, stats, reports
• events — tool, trace, and usage events
• harness — harness evaluation reports and dimension scores

You may keep a personal parent go.work that lists alternate clones on disk for multi-repo development.

The canonical inventory of sibling repositories is GrayCodeAI/graycode-eco/ecosystem.yaml, not the ecosystem.yaml in this repo, which is deprecated and incomplete. The inventory moved because a product must not own the registry of its siblings: it lived here, rho was renamed from hawk without signalling the other nine repositories, and the list silently omitted beam. See graycode-eco/adr/0001.

scripts/ecosystem-manifest.sh reads the roof's file and falls back to the deprecated local copy only when the roof is not checked out alongside.

flux is the only Go module dependency in the entire ecosystem; 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.

Development

Prerequisites

• Go 1.26+

Build & Test

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 report

Performance & Benchmarks

Published, 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):

Project Structure

rho follows Go conventions: cmd/ for entry points, internal/ for private code, tests alongside source files. See docs/architecture.md for details.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for development setup, commit conventions, and the PR process.

Quick start:

1. Fork and create a branch: git checkout -b feat/short-description
2. Make changes in small, focused commits
3. Run make ci locally
4. Open a pull request

Use Conventional Commits for commit messages. Releases are cut by hand from a release PR; see docs/RELEASING.md.

License

MIT — see LICENSE for details.

© 2026 GrayCode AI