Internals Overview

This section documents the internal mechanisms of Animus for contributors who want to understand how the system works beneath the CLI surface.

What's Covered

• Daemon Scheduler -- The tick loop that drives autonomous workflow dispatch, capacity management, and completion reconciliation
• Workflow Runner -- The standalone binary that executes workflow phases by coordinating with the agent runner
• Agent Runner IPC -- The IPC protocol between workflow-runner and agent-runner, including authentication, event streaming, and output parsing
• State Machines -- Workflow and task state machines, transition rules, and guard conditions
• Persistence -- Atomic file writes, JSON state schemas, and the scoped directory layout

Key Concepts

Tick loop: The daemon operates on a periodic tick. Each tick loads state, plans dispatches, reconciles completions, and spawns new workflow-runner subprocesses.

Subject dispatch: Every workflow execution targets a "subject" (typically a task). The dispatch queue orders subjects by priority and tracks their lifecycle from enqueued through assigned to terminal.

Three-process model: The daemon spawns workflow-runner processes, which in turn communicate with the agent-runner daemon over IPC. The agent runner manages the actual LLM CLI tool processes (claude, codex, gemini, opencode).

animus daemon (tick loop)
  └── workflow-runner (phase execution)
        └── agent-runner (LLM CLI management)
              └── claude / codex / gemini / opencode

Related Sections

• Architecture Overview -- Crate dependency graph and high-level design
• ServiceHub Pattern -- Dependency injection
• Crate Map -- All crates by responsibility