Skip to content

Development ​

Build and check the project with Cargo:

bash
cargo build
cargo test

Run the local binary without installing:

bash
cargo run --
cargo run -- run "summarize this repository"

Use the local binary to test the interactive TUI, automation mode, configuration, and tools behavior while developing.

Everything Cargo launches (cargo run and every test) keeps its data root (config, sessions, credentials) in target/rho-home in the checkout and uses the file credential store, so it never migrates or writes your real data or OS keyring. Global instructions, skills, agents, and prompts still load from ~/.rho, as they always do. .cargo/config.toml sets RHO_HOME and RHO_CREDENTIAL_STORE only when they are unset, and Rho treats an empty value as unset, so RHO_HOME= RHO_CREDENTIAL_STORE= cargo run runs exactly as the installed rho does. An exported RHO_HOME wins over this, so unset it before running tests. To reset the development home, for example when an older branch refuses a session index a newer build migrated, run cargo run -- daemon stop first (a development daemon outlives Cargo), then delete target/rho-home. Without XDG_RUNTIME_DIR (always on macOS) the daemon socket is <home>/run/daemon.sock, measured after symlinks resolve, so a target linked into a cache counts at its real location. On macOS a resolved home longer than 87 bytes passes the 103-byte socket limit and daemon commands fail with SocketPathTooLong; export a short RHO_HOME, such as /tmp/rho-dev, there.

RHO_FIRST_RUN opens the setup screen on a machine that already has config. It does not clear history or credentials.

bash
RHO_FIRST_RUN=signin rho
RHO_FIRST_RUN=model rho
RHO_FIRST_RUN=1 rho

signin opens the provider menu. model opens the model list. 1 opens whichever step a real first launch would open. On a configured machine that already lists models, 1 goes to the model step. To see the signed-out session, run /logout for the active provider.

Set RHO_LOG to a tracing env-filter to print spans on stderr. It is off by default. Examples: RHO_LOG=rho=info or RHO_LOG=rho=debug.

Local validation ​

Use the fast workflow while editing. It always checks formatting and architecture, then checks one package without compiling every target:

bash
python3 scripts/validate.py fast --package rho-sdk

You can add a library test, an integration test, or a test-name filter:

bash
python3 scripts/validate.py fast --package rho-sdk --lib
python3 scripts/validate.py fast --package rho-coding-agent --test automation_cli
python3 scripts/validate.py fast --package rho-coding-agent --test automation_cli --filter streams_json_events

Run the full workflow before opening or updating a pull request:

bash
python3 scripts/validate.py full

The full mode runs policy and script checks, Clippy for all targets and features, normal workspace tests, the docs TUI proof-plate PTY check against the rho binary those tests built, a rho check without dev-dependency features, documentation tests, and SDK feature and downstream checks. It stops at the first failure and prints per-step timings. Both modes cap Cargo at 8 jobs. A lower CARGO_BUILD_JOBS value remains in effect. They also set RUST_MIN_STACK to at least 16 MiB so rustc 1.92 does not overflow its 8 MiB compile-thread stack.

Development and test profiles use reduced debug information to keep artifacts and link times smaller while retaining line-number backtraces. Set CARGO_PROFILE_DEV_DEBUG=2 or CARGO_PROFILE_TEST_DEBUG=2 when a debugging session needs full symbols.

Changing the daemon protocol ​

While PROTOCOL_VERSION in crates/rho-protocol/src/version.rs is 0.x, a change to the wire (anything in crates/rho-protocol/schema/protocol.json other than descriptions and names) does not raise its minor: nothing of the protocol is released while 3.0 is built, so the version stays as it is and is set once, at the beta. Do not raise it in a pull request. Until then a frontend and a daemon of different builds may report the same version and still differ, so run both from one build (Versions). Regenerate the schema after a change:

bash
cargo run -p rho-protocol --example protocol_schema > crates/rho-protocol/schema/protocol.json

The version a hello names and the data of the error that refuses it are the exception: clients and daemons of every version read them, so they only ever gain optional fields.

CI still holds that exception, and that the version never goes down, comparing each pull request with its base and each push with the commit before it. To run the same check against your base:

bash
python3 scripts/check_protocol_compat.py --baseline-ref origin/daemon-v3 --unstable-only

Changing the A2UI core ​

crates/rho-a2ui is rho's A2UI v1.0 core. It loads and validates catalogs, applies an agent's messages to surfaces on the renderer side, and compiles and decompiles A2UI Express, the compact notation a model writes a surface in. It is released and published on its own as rho-a2ui, so clients such as rho-ui can use it without the rest of rho. Its README lists what it holds.

It is tested against the conformance suites Google publishes with A2UI, vendored unmodified under crates/rho-a2ui/vendor/a2ui with their Apache-2.0 license. cargo test -p rho-a2ui runs each suite as one test, and the README lists each suite's status. Never edit a vendored file. To refresh them from a checkout of google/A2UI, or after adding a path to vendor/a2ui/FILES:

bash
crates/rho-a2ui/scripts/vendor-a2ui.sh <upstream-checkout>

Crate publish preparation ​

CI runs scripts/check_crate_publish_prep.sh before release packaging. That script calls scripts/crate_publish_prep.py, which dry-runs cargo publish for each independently released crate.

Internal path dependencies use this registry-boundary rule:

  • If every internal dependency's exact workspace version already exists on crates.io (including yanked releases), verify against the registry. Do not path-patch any dependency.
  • If any direct internal dependency version is not on crates.io yet, path-patch the full transitive internal dependency closure of the package under test. Path-source crates keep path = edges to siblings; patching only the unpublished leaf would load a second copy of shared crates such as rho-sdk and break type identity. The closure patch keeps one graph so a coordinated same-PR version cut can still package before dependencies are published.
  • crates.io transport or HTTP failures fail the check. A timeout or 500 is not treated as "unpublished".

This catches the failure mode where a refactor moves public symbols into a dependency without cutting that dependency's version: local workspace builds still pass, but cargo publish verification against crates.io does not.

scripts/publish_workspace_crates.sh --dry-run uses the same patch selector. Real publishes never path-patch; they wait for each dependency version to index on crates.io first.

Local checks:

bash
python3 scripts/crate_publish_prep.py --self-test
./scripts/check_crate_publish_prep.sh

The self-test uses fixtures/publish-boundary, where a consumer imports a symbol that exists only on the workspace copy of a dependency. Without a workspace path patch, verification fails the same way a real crates.io publish would.

Thermo-nuclear review workflow ​

The repository includes .rho/workflows/thermo-nuclear-review/ for a deep review of the current branch. It collects one bounded Git context pack, runs three read-only review lanes in parallel, then sends their structured findings to one worker that applies safe fixes. A final shepherd agent validates, commits, and pushes the fixes, opens the PR if none exists, and babysits it until it is approved with green CI and no unresolved review thread. It never merges, and it only acts on review requests from trusted repository members or verified review bots. If the selected scope has no changes, the workflow skips the review and fix agents and goes straight to babysitting the branch PR.

bash
rho workflow validate .rho/workflows/thermo-nuclear-review/workflow.star
rho workflow plan .rho/workflows/thermo-nuclear-review/workflow.star \
  --input 'base="main"' \
  --input 'scope="all"'

base must resolve exactly; an invalid explicit ref does not fall back to a different branch. scope accepts all, committed, or uncommitted. See .rho/workflows/thermo-nuclear-review/README.md for its graph, inputs, run commands, and context collector test.

Test selection ​

Before adding, expanding, reviewing, or deleting tests, follow the project skill rho-test-selection at .agents/skills/rho-test-selection/SKILL.md. It defines the failure-mode / owner-layer gate, Tier A/B/C rules, determinism requirements, and PTY-as-product-gate defaults.

Pull requests that add tests should fill the test-gate section in the pull request template.

Test prerequisites ​

CI and python3 scripts/validate.py full run the workspace tests with cargo-nextest (cargo install cargo-nextest --locked). Nextest runs each test in its own process and schedules across test binaries, so a test that races another binary's tests fails there even when cargo test passes. Doctests stay on cargo test --doc.

Some integration tests spawn local fixtures and need host tools on PATH:

  • stdio_lifecycle_and_failure_isolation in crates/rho/src/tools/mcp_tests.rs is Unix-gated and requires python3 to run its stdio MCP server fixture.

Interactive TUI PTY harness ​

Rho includes a deterministic PTY harness in crates/rho-tui-pty for automated interactive TUI tests. Prefer it over manual Herdr smoke tests for regressions that can be expressed as scripted scenarios. PTY is the product gate for interactive behavior; unit tests under crates/rho/src/tui stay limited to pure logic.

Layers ​

  • PTY controller - spawn a selected rho binary in a pseudo-terminal, inject keys/paste/mouse, resize, drain output, and kill-on-drop
  • Screen model - reconstruct the visible terminal with a VT parser and assert user-visible text
  • Scenarios - named action/assertion sequences over RHO_TUI_TEST_MODE=matrix
  • Artifacts - on failure, keep raw PTY bytes, reconstructed screen, action log, and redacted env

The controller supports Unix PTYs and Windows ConPTY. The broader scenario suite still targets Unix; a shared native smoke test exercises startup, multiline Unicode paste, composer navigation, submission, and exit on Windows as well. The harness compiles crates/rho/src/pty.rs by path instead of depending on rho-coding-agent, so the Cargo workspace (and release-please's cargo-workspace plugin) stay acyclic.

Run harness self-tests ​

bash
cargo test -p rho-tui-pty

Run the CI smoke scenarios ​

bash
cargo test -p rho-coding-agent --test tui_pty

Smoke scenarios cover startup/stream/exit, cancel-and-resubmit, resize-during-stream, scroll-during-stream, and terminal restoration.

On Linux, the startup smoke test launches Rho with a 1 MiB main-thread stack, matching the Windows linker default. This catches debug async-frame overflows that Linux's larger default stack would hide.

The native smoke test runs in the Linux, macOS, and Windows workspace CI jobs:

bash
cargo test -p rho-coding-agent --test tui_pty_native --jobs 8

Windows uses ConPTY, which requires Windows 10 version 1809 or later. This focused test does not replace the Unix scenario suite or prove every Windows terminal interaction.

Run one scenario locally ​

bash
cargo build -p rho-coding-agent
cargo run -p rho-tui-pty --bin rho-pty-scenario -- --list
cargo run -p rho-tui-pty --bin rho-pty-scenario -- --bin target/debug/rho startup_stream_exit
cargo run -p rho-tui-pty --bin rho-pty-scenario -- --bin target/debug/rho --smoke
cargo run -p rho-tui-pty --bin rho-pty-scenario -- --bin target/debug/rho --timing startup_stream_exit
cargo run -p rho-tui-pty --bin rho-pty-scenario -- --bin target/debug/rho --timing startup_first_frame

--timing records wait latency samples. For first-frame paint, compare the named wait_for_text:rho sample rather than mixed p50/p95/p99 across unrelated waits. Do not treat those milliseconds as a CI budget.

Failure artifacts default to a temp directory (or --artifacts <dir>). Successful runs do not retain artifacts.

Regenerate the docs TUI proof plate ​

Dark and light proof plates are captured from one matrix-mode PTY session (not hand-drawn), then rendered with two SVG palettes:

  • dark (README + site): docs/assets/rho-ui-demo.svg and docs/public/assets/rho-ui-demo.svg
  • light (site only): docs/public/assets/rho-ui-demo-light.svg

After TUI layout or chrome changes, regenerate those paths:

bash
bash scripts/check_docs_ui_demo.sh --write

Detect drift without writing:

bash
bash scripts/check_docs_ui_demo.sh --check

The CI quality job and python3 scripts/validate.py full run the check. The generator needs a Unix PTY and a debug build because RHO_TUI_TEST_MODE=matrix is debug-only. Load-volatile fragments (tool durations and statusline usage) are pinned in the SVG. The header package version is pinned at capture input via RHO_TUI_DISPLAY_VERSION so release bumps do not force a regen.

Environment isolation ​

Scenarios launch Rho with:

  • temporary HOME and --config
  • RHO_TUI_TEST_MODE=matrix (debug builds only)
  • host terminal markers stripped (TMUX, TERM_PROGRAM, Herdr vars, editor markers, and related identity env)
  • web_search.mode = "off" in the isolated config.toml and check_for_updates = false in its clients/tui.toml

When to use Herdr instead ​

Run Rho in a separate Herdr pane for exploratory checks, novel bugs that are not yet encoded as scenarios, or parity checks against a real terminal renderer. A debug build started with RHO_TUI_TEST_MODE=matrix uses the same offline fixture provider as the PTY scenarios.

Performance investigations ​

Run performance comparisons ad hoc. Record the commands, source commits, environment, results, and interpretation in the pull request body. Do not commit benchmark code, result reports, or comparison charts.

Workflow limits and cancellation tests ​

Workflow planning policy lives in crates/rho/src/workflow/planning_limits.rs. Named budgets cover source modules, evaluator work and heap, values, graph structure, schemas, runtime output, templates, prompts, argv, and inputs. Runtime limits are frozen into the plan. Budget errors identify the budget, limit, and requested value.

The evaluator heap metric matches Starlark's enforced quantity: mutable-heap peak plus frozen-heap allocated bytes. graph_bytes covers the entire serialized scoped program, including its root and input schemas, rather than just the root graph. The planner process also has a coarse OS memory backstop: RLIMIT_AS on Linux and a Job Object process-memory commit limit on Windows.

Workflow schema v1 forbids source-controlled environment entries; environment_expansion_bytes keeps a one-byte budget floor.

The cross-process cancellation acceptance test starts a real workflow owner, waits on a Unix socket until a compiled command node is active, and starts a second Rho process to run workflow cancel. Linux pidfd_open checks that the command process exits. Explicit readiness and process completion synchronize the test; deadlines bound acknowledgement and cleanup without collecting timing samples.

After building Rho, run:

bash
python3 scripts/test_workflow_cancellation.py --rho target/debug/rho

The test requires Linux with Unix sockets and pidfd_open, and rustc on PATH. It isolates HOME and RHO_HOME in a temporary directory so local agents and credentials cannot affect the result.

Provider identity and auth modes ​

A provider identifies one API or product surface. If two login methods use the same API base, wire protocol, and model catalog, add both to that provider's auth_modes list rather than adding a second provider. The first mode is the default. Keep separate providers when endpoints, protocols, catalogs, or product surfaces differ. For example, OpenRouter API-key and OAuth access share openrouter, while the OpenAI API and Codex remain openai and openai-codex.

When retiring a same-API provider name, add a load-time alias that selects both the canonical provider and the matching auth mode. New config, model references, favorites, runtime identities, and cache entries must use the canonical provider name.

Model integration layers ​

Model integrations are split into three layers:

  • crates/rho-providers/src/model/ defines provider registry, catalog, and application model support without wire types.
  • crates/rho-providers/src/protocol/ converts the canonical SDK model to and from API wire formats. OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Google Gemini Generate Content are implemented here.
  • crates/rho-providers/src/providers/ owns credentials, endpoint selection, headers, retries, continuation state, and transport policy for each provider. Multiple providers may consume one protocol codec.

Keep provider-specific fields in protocol or provider modules unless the agent needs the underlying concept. Adding a protocol stub does not make a provider available: provider identity, authentication, model discovery, runtime construction, and documentation must be implemented separately.

Architecture guardrails ​

Run the lightweight architecture checks before submitting structural changes:

bash
python3 scripts/check_architecture.py
python3 scripts/check_architecture.py --self-test

The script uses only the Python standard library and reads policy from scripts/architecture.json. It enforces these repository policies:

  • Hand-written production Rust files under workspace crate src/ directories, plus crate build.rs files, have a 1,000-line default budget (default_production_line_budget).
  • Dedicated test files, including files under a tests/ directory and *_test.rs, *_tests.rs, or tests.rs, are excluded. Inline tests still count toward their production file's budget.
  • Generated Rust files are excluded only when their exact path and reason are recorded in generated_files in scripts/architecture.json. There are currently no generated-file exclusions.
  • Existing oversized production files are listed explicitly in legacy_file_budgets. Their ceilings prevent further growth and should be lowered or removed as the files are split.
  • crates/rho-providers/src/credentials must remain independent of model, keeping credential storage separate from model runtime metadata (forbidden_dependencies).
  • crates/rho/src/main.rs has a 50-line thin-binary budget so application orchestration remains in the library (thin_binary_budgets).
  • Package dependency boundaries are also declared in forbidden_package_dependencies so lower-level crates cannot depend on the application or reverse the intended layering. crates/rho-protocol depends on no other rho crate, so an SDK or application major release cannot break frontends that only speak the daemon protocol. crates/rho-a2ui depends on no other rho crate either, so clients such as rho-ui can use the A2UI core without the rest of rho.

Current legacy file budgets are: none.

Do not raise a budget just to make a check pass. Prefer extracting a cohesive module and reducing the recorded ceiling. If a generated file must be added, list its exact repository-relative path with a non-empty reason so the exclusion remains reviewable. When changing the scanner or policy, update its self-tests and this documentation together.

Rust toolchain and MSRV ​

The rho-sdk minimum supported Rust version (MSRV) is 1.86. The rho-coding-agent application MSRV is 1.92 because its terminal, credential, and terminal-native Mermaid rendering dependencies require a newer compiler. Both values are declared as package.rust-version in Cargo metadata and tested in CI.

rustc 1.92.0's default compilation-thread stack is 8 MiB. Type-checking this workspace's dependency graph (and some individual crates such as hashbrown, syn, toml_edit, and num-traits) overflows that stack. rustc reports it as SIGSEGV plus RUST_MIN_STACK=16777216, or as a query ICE (active query job entry / DepNodeIndex pack assert). .cargo/config.toml sets RUST_MIN_STACK to 16 MiB when the variable is unset. validate.py raises any smaller value to that floor and caps Cargo at 8 jobs. Override the job cap with CARGO_BUILD_JOBS or cargo -j.

When either MSRV changes, update the matching Cargo manifest, this section, and CI together. An MSRV increase must not ship as a patch release. On a stable major line, an SDK MSRV increase requires at least a minor version increase and must be called out in release notes. Emergency compiler requirements caused by a security or soundness fix may skip normal notice, but still require coordinated metadata and CI updates.

Embedders only need the SDK crate's declared package.rust-version. See SDK installation.