Tools

trusty-agents — documentation

trusty-agents (crates/trusty-agents/, binary tagent) is a Rust-native AI agent orchestration harness: a long-running CTRL controller coordinates per-project PM actors, each of which delegates work to specialized sub-agents that run either in-process (fast, read-only) or as isolated OS subprocesses communicating over NDJSON IPC. Its defining differentiator is model-agnostic dispatch — any agent role can be backed by OpenRouter, the direct Anthropic API, AWS Bedrock, or the claude CLI OAuth path, assignable per-agent via a two-line TOML change. trusty-agents consumes the shared trusty-* libraries (trusty-search, trusty-memory-core, trusty-symgraph).

This directory is the single source of truth for trusty-agents design, research, specification, and user/developer documentation. (Rustdoc and the crate README.md stay in-crate; see ADR-0001.)

Documentation map

Subdir	What's here
`spec/`	Canonical specification set: PRD, ARCHITECTURE, COMPONENTS. Start here for what trusty-agents is, how it fits together, and the per-subsystem detail.
`research/`	~70 investigation, audit, and design docs that shaped trusty-agents — frameworks, IPC patterns, dispatch, token compression, UI surfaces, bug analyses. Indexed in `research/README.md`.
`design/`	Focused design notes: workflow engine, CTRL REPL, design goals. Visual assets (icon, treatment PDF) live in `design/visual/`.
`developer/`	Contributor docs: architecture overview, building, contributing, testing.
`user/`	End-user docs: quickstart, CLI reference, configuration, agents & skills.
`architecture/`	Cross-cutting architecture notes: agent/skill design, drift detection.
`regression-testing/`	Performance baselines, bake-off comparisons, and the per-run telemetry tooling (`analyze.py`, `runs.log`). See `PERFORMANCE.md` for the run-file schema.
`sessions/`	Engineering-session narratives and end-to-end user-story walkthroughs.
`decisions/`	Crate-specific ADRs (Nygard format). Workspace-wide ADRs live in `docs/adr/`.

Where to start

New to trusty-agents? spec/PRD.md → spec/ARCHITECTURE.md → spec/COMPONENTS.md.
Installing / using it? user/quickstart.md.
Contributing? developer/contributing.md and developer/building.md.
Understanding a past decision? decisions/ (crate-specific) or docs/adr/ (workspace-wide).

Conventions

Subdirs follow the workspace documentation conventions described in the root CLAUDE.md. The spec/ set is a living document; research/ files are dated point-in-time investigations preserved as-is.