ryo — AST-centric programming for AI agents.
ryo is an AST-based code transformation engine for Rust, designed to be driven by AI coding agents (Claude, GPT, etc.) rather than by hand-edited text.
Instead of generating code as strings, agents describe what they want to change using structured Intents, and ryo applies the change safely against the live AST — discovery, graph analysis, and transformation share one model.
v0.1.0 — early release. Public API surface may shift before v0.2.
| Surface | Stability |
|---|---|
ryo discover / ryo graph (Reader path) |
Stable enough to script against |
ryo suggest / Intent transforms (Writer path) |
Experimental — review every diff |
| Internal crate APIs | Unstable, expect breakage |
The Reader path (read-only AST + graph queries) is the recommended entry point for agents today. The Writer path (mutating Intents) is usable but should be gated behind human review.
# From crates.io (recommended once published)
cargo install ryo-cli
# From source
git clone https://github.com/ynishi/ryo-rs
cd ryo-rs
cargo install --path crates/ryo-cliRequires a recent stable Rust toolchain (edition 2021).
All commands run against the current Rust project (-p .).
ryo discover "Config" -p .
ryo discover "AnalysisContext" --view def -p .discover walks the workspace, locates symbols by name pattern or SymbolId,
and can render the definition, callers, callees, or full body.
# Who calls this function?
ryo graph chain --id <SID> --mode callers --depth 5 -p .
# What does this type touch?
ryo graph type "SymbolId" --mode impact -p .
# What breaks if I change this?
ryo graph cascade --id <SID> --depth 3 -p .The graph model is bidirectional across four axes: Call, Type,
Trait, and Structure. Each axis exposes both forward edges
(Calls, TypeReferences, …) and reverse edges (CalledBy,
TypeReferencedBy, …).
ryo query 'kind: Function, match: { name: process }'RyoQL is a small YAML/JSON-shaped query language for agents.
It compiles to the same AST graph queries used by discover / graph.
ryo guide cheatsheet # list available Intents
ryo guide <intent-name> # show how to invoke one
ryo suggest --quick -p . # heuristic suggestions over the workspaceWriter-path commands are experimental — see Status.
Code-search and code-edit tools built for humans (grep, IDE refactor menus) assume a human eye in the loop. AI agents working at scale need different properties:
- One model, many views. Discover, graph traversal, and transformation all read from the same in-memory AST + symbol graph. No re-parse round-trips.
- Structured Intents, not text patches. Agents describe what to change.
ryo handles
useupdates, brace matching, and similar mechanical concerns. - Bidirectional graph. Reverse edges (callers / users / impls) are first-class, so impact analysis is a query, not a grep loop.
- AST-first views.
ryo viewreturns module hierarchy + signatures + reference graph in one structured response sized for an LLM context window.
If you are building tooling for AI coding agents (rather than for humans typing in an editor), ryo is meant to be the layer between the agent and the source tree.
ryo is organised as a workspace of focused crates, layered bottom-up:
Layer 4 Entry ryo-cli | ryo-ui | ryo-agent
──────────────────────────────────
Layer 3 Orchestration ryo-app
──────────────────────────────────
Layer 2 Execution ryo-executor | ryo-suggest | ryo-storage
──────────────────────────────────
Layer 1 Domain ryo-mutations | ryo-analysis
──────────────────────────────────
Layer 0 Foundation ryo-source | ryo-spec
- Layer 0 Foundation — AST primitives and domain markers.
- Layer 1 Domain — transformation primitives and symbol/graph management.
- Layer 2 Execution — runs Intents, generates suggestions, persists graphs.
- Layer 3 Orchestration — interprets user/agent Intents end-to-end.
- Layer 4 Entry — three sibling entry points sharing the same
Api: CLI (ryo-cli), agent-facing RPC (ryo-agent), and TUI (ryo-ui).
Layer 3 enforces a Reader / Writer split:
read paths are thread-safe and lock-free, write paths require exclusive access.
Full design notes live under docs/.
Runnable quickstarts live under examples/ (added in the
following point release — see issue 1.7 in workspace/releases/0.1.0.md):
examples/reader-quickstart/— discover + graph traversal walkthrough.examples/writer-quickstart/— applying an Intent end-to-end.
For a tour of common workflows, see:
docs/cookbook.md— recipe-style command examples.docs/discover-workflow.md— the two-step discover model.docs/view-workflow.md—ryo viewfor full context windows.docs/RyoQL.md— the query language reference.docs/crate-architecture-design.md— full crate-by-crate breakdown.
ryo is one of three sibling tools we use for agent-native development:
- algocline — a Lua-driven orchestration runtime for composing agent flows.
- agent-block — reusable blocks (skills, recipes, MCP servers) that those flows compose.
- ryo (this repo) — the AST/graph layer that lets those agents read and edit Rust source structurally.
They are independent crates / repos; you can use ryo on its own.
ryo is in active development and the public API is not yet frozen. Issues, discussions, and small PRs are welcome — for larger changes please open an issue first so we can align on the Intent before code review.
Development notes, design docs, and pipeline rules live under
docs/ and workspace/ (the latter is git-ignored and intended
for local agent state).
Dual-licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.