How It Works

How It Works

Four pieces make anvil run: the daemon, task files, the scheduler, and the worker pool.

The Daemon

Run anvil watch to start the daemon. It runs in the background and watches all projects you've initialized. One daemon per machine handles everything.

The daemon:

• Watches for new or modified task files in .anvil/todos/
• Checks schedules every few seconds
• Dispatches tasks when their schedule fires
• Manages the worker pool

Task Files

Each task is a markdown file in .anvil/todos/. The file contains:

• YAML frontmatter with configuration (schedule, priority, retry settings)
• Plain English instructions for Claude in the body

Example:

---
schedule: "*/30 * * * *"
priority: 1
---
Check GitHub for new issues and triage them

Create tasks with anvil add or by writing files directly.

The Scheduler

The scheduler evaluates each task's cron expression. When a schedule matches:

1. Task enters the priority queue
2. Waits for an available worker
3. Dispatches to Claude for execution

Lower priority numbers run first. Task p0 runs before p1, p1 before p2, etc.

Worker Pool

The daemon maintains a pool of workers (default: 10). Each worker runs one task at a time through Claude.

If a task is already running and its schedule fires again, the task is skipped.

Persistent Tasks

For continuous workloads, use persistent as the schedule:

---
schedule: "persistent"
---
Monitor a queue and process items

The task completes, then re-dispatches on the next scheduler tick.

Session Continuity

Recurring tasks maintain session context. If a task processes a large dataset and gets interrupted, the next run can pick up where it left off using checkpointing or state management.