Development Guide

Prerequisites

• Rust -- install via rustup
• Cargo -- comes with Rust; the workspace uses resolver v2
• Git -- required for repo root resolution and worktree operations

Build Commands

cargo animus-bin-check
cargo animus-bin-build
cargo animus-bin-build-release

Run the CLI directly:

cargo run -p orchestrator-cli -- --help

Build a specific crate:

cargo build -p protocol
cargo build -p orchestrator-core
cargo build -p agent-runner

Workspace Structure

The workspace is a Cargo workspace of 18 crates. The core orchestrator crates are:

crates/
├── agent-runner/
├── animus-plugin-protocol/
├── animus-plugin-runtime/
├── animus-subject-protocol/
├── oai-runner/
├── orchestrator-cli/
├── orchestrator-config/
├── orchestrator-core/
├── orchestrator-daemon-runtime/
├── orchestrator-git-ops/
├── orchestrator-logging/
├── orchestrator-notifications/
├── orchestrator-plugin-host/
├── orchestrator-providers/
├── orchestrator-session-host/
├── orchestrator-store/
├── protocol/
└── workflow-runner-v2/

Repo-local but not current workspace members:

• crates/animus-plugin-smoke/
• crates/animus-provider-mock/
• crates/orchestrator-web-server/

default-members in Cargo.toml include:

• orchestrator-cli
• agent-runner
• oai-runner

Key Dependencies

Dependency	Usage
anyhow	Error propagation
clap	CLI argument parsing
tokio	Async runtime
serde / serde_json	State and IPC serialization
serde_yaml	Workflow config parsing
uuid	IDs for tasks, workflows, and runs
fs2	File locking for concurrent state access
rusqlite	Repo-scoped workflow/task/requirement persistence
rmcp	MCP server and client support
webbrowser	Browser-launch helper for animus web open
croner	Schedule parsing

Documentation Site

The docs are powered by VitePress.

The web dashboard itself is no longer an in-tree web server. animus web delegates to installed transport_backend and web_ui plugins.

npm install
npm run docs:dev
npm run docs:build
npm run docs:preview

Protocol schema exports live at the repo root:

cargo run -p animus-plugin-protocol --bin animus-plugin-protocol-export-schema
cargo run -p animus-subject-protocol --bin animus-subject-protocol-export-schema

Those commands write to /schemas/animus-plugin-protocol/ and /schemas/animus-subject-protocol/ under the workspace root. Do not commit accidental crate-local output such as crates/orchestrator-cli/schemas/.

Project Conventions

• All CLI --json output follows the animus.cli.v1 envelope
• Always use --project-root "$(pwd)" in scripts and automation
• Treat .animus/ project config and ~/.animus/<repo-scope>/ runtime state as Animus-managed data
• Prefer source files over prose when documenting command counts, crate counts, and runtime paths