AI-Assisted Development

You want AI coding agents (Claude Code, Cursor, Copilot) to build, test, and fix your HORUS project autonomously. HORUS provides structured JSON diagnostics with fix commands, machine-readable API extraction, and diff-based change detection so agents can work without parsing compiler output with regex.

When To Use This

• Setting up a HORUS project for AI-assisted vibe coding
• Configuring CLAUDE.md or similar agent instructions for HORUS
• Using --json-diagnostics for automated error resolution in CI
• Extracting API surface as JSON/Markdown for LLM context windows

Use AI Integration instead if you want to embed ML models inside your robot, not use AI tools to write code.

Prerequisites

• A HORUS project with horus.toml
• An AI coding agent (Claude Code, Cursor, or any tool that can execute shell commands)

The AI Development Loop

An AI agent working on a HORUS project follows this loop:

1. Understand the project    horus doc --extract --json
2. Build and check           horus build --json-diagnostics
3. Parse errors              (structured JSON, one per line)
4. Auto-fix                  Execute the "fix" command from each diagnostic
5. Run tests                 horus test
6. Check what changed        horus doc --extract --diff baseline.json
7. Repeat

Every step produces machine-readable output. No regex parsing of compiler errors needed.

Structured Error Diagnostics

Enable JSON diagnostics

horus build --json-diagnostics
horus run --json-diagnostics

Every error, warning, and hint is emitted as a JSON object on stderr:

{"tool":"cargo","code":"H001","severity":"error","message":"Crate 'serde' not found on crates.io","hint":"Check the name or add it with:\n  horus add serde","fix":{"type":"command","command":"horus add serde"},"docs_url":"https://horus.dev/errors/missing-crate"}

The Fix Field

Every diagnostic includes a fix field that the AI agent can execute directly:

{
  "fix": {
    "type": "command",
    "command": "horus add serde"
  }
}

The agent parses this, runs horus add serde, and the dependency is installed. No guessing.

Error Code Catalog

Diagnostics use standardized codes (H001-H064) grouped by tool:

JSON Output for Build/Test Results

# Build with JSON result
horus build --json
# Output: {"success": true, "command": "build"}
# Or:     {"success": false, "command": "build", "errors": [{"message": "..."}]}

# Test with JSON result
horus test --json
# Output: {"success": true, "command": "test"}

API Extraction for Context

AI agents need to understand the project's API surface before making changes. horus doc --extract provides this in a single command.

Quick Overview

# Brief text summary (fits in any context window)
horus doc --extract

Output:

# my_robot v0.1.0 — 24 symbols, 78% documented
# 3 nodes, 4 messages, 5 topics

## Message Types
  CmdVel { linear: f32, angular: f32 }
  Odometry { x: f64, y: f64, theta: f64 }

## Nodes
  ControllerNode (impl Node) [100hz, Rt]
    pub -> cmd_vel: CmdVel
    sub <- odom: Odometry
  SensorNode (impl Node) [200hz, Rt]
    pub -> imu: ImuReading

## Topic Graph
  cmd_vel: CmdVel      ControllerNode -> MotorDriver
  odom: Odometry        MotorDriver -> ControllerNode

## src/controller.rs — PID controller
  struct ControllerNode { pid: PidState }
    impl Node
    fn new(kp: f64, ki: f64, kd: f64) -> Result<Self>

Full JSON for Programmatic Access

horus doc --extract --json

Returns a ProjectDoc with:

• All symbols (functions, structs, enums, traits, messages, services, actions)
• Doc comments and deprecation annotations
• Trait implementations and method associations
• Message flow graph (which nodes publish/subscribe to which topics)
• Entry points (main functions, Node implementations)
• Documentation coverage statistics

Markdown for LLM System Prompts

horus doc --extract --md > api.md

Produces markdown suitable for injecting into an LLM's context window. Include in your CLAUDE.md or system prompt:

# Project API Reference
Run `horus doc --extract --md` for current API surface.

Write to File

horus doc --extract --json -o api.json
horus doc --extract --html -o docs/api.html

Filter by Language

horus doc --extract --lang rust      # Only Rust symbols
horus doc --extract --lang python    # Only Python symbols

API Diff for Change Detection

Compare the current API against a saved baseline to detect breaking changes:

# Save baseline (e.g., on main branch)
horus doc --extract --json -o baseline.json

# After changes, diff against baseline
horus doc --extract --diff baseline.json

Output:

API Changes:

  Added:
    + src/sensors/lidar.rs: function pub fn calibrate(&mut self)

  Removed:  [!] BREAKING
    - src/legacy.rs: function pub fn old_handler()

  Changed:
    ~ src/controller.rs: function compute
      was: pub fn compute(&mut self, setpoint: f64, measurement: f64) -> f64
      now: pub fn compute(&mut self, setpoint: f64, measurement: f64, dt: f64) -> f64
      [!] BREAKING: added parameter `dt: f64`

  Summary: +1 added, -1 removed, ~1 changed, 1 breaking changes

CI Integration

# Fail CI if breaking changes detected
horus doc --extract --diff baseline.json
# Exit code 1 if breaking changes found, 0 otherwise

Documentation Coverage Gate

# Fail if coverage drops below 60%
horus doc --extract --coverage --fail-under 60

Watch Mode for Live Development

# Regenerate docs on every file save
horus doc --extract --watch

# Write to file on every change
horus doc --extract --json --watch -o api.json

The agent can poll api.json to stay updated as the code changes.

Self-Contained HTML Report

horus doc --extract --html -o api-docs.html

Generates a single HTML file with:

• Embedded CSS (dark mode support)
• Client-side search
• Collapsible module sections
• SVG topic flow graph
• Coverage table
• TODO/FIXME list

No external dependencies — works offline, safe to share.

Typical Agent Workflow

Step 1: Understand the project

horus doc --extract --json -o api.json
# Agent reads api.json, understands:
# - What nodes exist and their topics
# - What message types are defined
# - What the public API surface looks like

Step 2: Make changes

The agent edits source files based on the API understanding.

Step 3: Build and auto-fix

horus build --json-diagnostics 2> errors.jsonl
# Agent parses each line, extracts "fix" commands, executes them
# Example: {"fix": {"type": "command", "command": "horus add tokio"}}
#   Agent runs: horus add tokio
# Rebuild until no errors

Step 4: Verify

horus test --json
horus doc --extract --diff baseline.json --json
# Agent checks: tests pass? Any breaking changes?

Step 5: Report

horus doc --extract --coverage
# Agent reports: documentation coverage, new symbols, changes

CLAUDE.md Integration

Add to your project's CLAUDE.md for AI agents:

## Build Commands
horus build --json-diagnostics  # Build with structured errors
horus test --json               # Run tests
horus doc --extract --json      # Get API surface

## Auto-Fix Workflow
When build fails, parse stderr JSON lines.
Each diagnostic has a "fix" field with a command to run.
Execute fix commands, then rebuild.

## API Understanding
Run `horus doc --extract --brief` to see the project API.
The topic graph shows message flow between nodes.

Common Errors

See Also

• CLI Reference — Full horus doc, horus build, and horus test command options
• Testing — Writing and running tests that AI agents can verify
• Error Handling — Error types, severity, and the codes referenced by diagnostics
• Static Analysis — horus check, horus lint, and horus fmt for code quality
• AI Integration — Embedding ML models in HORUS nodes (complementary topic)