aura: Instructions file for Claude Code

CLAUDE.md - Project Documentation

If CLAUDE.local.md exists in this directory, read it first — it contains current session state.

Overview

AURA is a TOML-based configuration system for composing Rig.rs AI agents with MCP tools and RAG pipelines.

Current Status: Production Ready

All major features complete:

• Bounded streaming with custom aura events
• Rig 0.28 upgrade with ProviderAgent architecture
• Configurable MCP header forwarding (headers_from_request with static TOML fallback)
• Request-scoped MCP progress and cancellation
• Client disconnect detection with MCP notifications/cancelled
• Multi-agent orchestration mode with coordinator/worker architecture and DAG execution

Pending: Upstream Rig PRs - StreamingPromptHook fix + Content-Type header fix

---

Quick Start

# Build
cargo build --release

# Start web server (default config.toml)
cargo run --bin aura -- webserver

# Start with orchestration config
CONFIG_PATH=configs/example-math-orchestration.toml AURA_CUSTOM_EVENTS=true cargo run --bin aura -- webserver

# Build and run CLI (HTTP mode — connects to a running `aura webserver`)
cargo run -p aura-cli -- --api-url http://localhost:8080

# Build and run CLI (standalone mode — no server needed, default when --api-url absent)
cargo run -p aura-cli -- --config configs/my-agent.toml

# Run integration tests (local, requires Docker)
make test-integration-local                        # base integration
make test-integration-orchestration-local          # orchestration integration
make test-integration-sre-orchestration-local      # SRE orchestration integration

Project Structure

aura/
├── crates/
│   ├── aura/                 # Core library (agent builder + orchestration)
│   ├── aura-cli/             # The `aura` binary: interactive client + `webserver` mode
│   ├── aura-config/          # TOML parsing and configuration
│   ├── aura-events/          # Shared SSE event types (lightweight, no agent deps)
│   ├── aura-web-server/      # OpenAI-compatible API + shared server entry point
│   └── aura-test-utils/      # Shared testing utilities
├── compose/                  # Docker Compose (integration + orchestration overlays)
├── configs/                  # Integration test and example configurations
├── deployment/               # Helm charts and K8s manifests
├── docs/                     # Architecture and protocol documentation
├── examples/                 # Example and reference configurations
└── .makefiles/               # Modular Make targets (rust, docker, node, aura)