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 configuration. trusty-agents integrates with trusty-search and trusty-memory and reuses the workspace's common MCP and agent libraries.

This directory is the extended index for trusty-agents design, research, and user/developer documentation. Implemented behavior remains code-owned; start with the crate README and current workspace behavior contracts.

Documentation map

Subdir	What's here
`spec/`	Historical pre-rename PRD, architecture, and component baseline.
`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? Start with the crate README and current product spec.
Desktop projects, channels, and skills? user/desktop-workspace.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 legacy spec/ set and research/ files are point-in-time evidence; current behavior is established by source, current READMEs, ADRs, and workspace behavior contracts.