Daemon

/daemon -- Continuous Autonomous Operation

Architecture, daemon.json field reference, and rationale: docs/DAEMON.md.

Orientation

Use when: running campaigns overnight or unattended -- chains sessions automatically until a ceiling or budget is hit. Don't use when: a single autonomous session is enough (use /archon); you want manual control between cycles (use /loop).

Default execution path (READ FIRST)

/daemon start does NOT call RemoteTrigger by default. The local runner is the default. Only pass --remote to use Anthropic's routine system, and only after explicit user confirmation.

Why: RemoteTrigger counts against the account-wide 15 routine runs / 24h cap. A single overnight run can exhaust the quota and pause every other routine on the account (including unrelated ones). See docs/ROUTINE-QUOTA.md.

Default flow — /daemon start (no --remote flag)

1. Do Steps 1, 2, and 4 below (validate, check existing, write daemon.json).
2. Skip Step 3 — do NOT create any RemoteTrigger. Leave chainTriggerId and watchdogTriggerId as null in the state file.
3. Instead of Step 5's trigger-confirmation, output the local-runner instructions (full text: docs/DAEMON.md#local-runner-default): the state file path, campaign, and budget, then:

   To start the tick loop, run in a separate terminal:
     npm run daemon:local
   
   Leave that terminal open. It spawns `claude --permission-mode default -p "/do continue"` each
   session, respects daemon.json status, and consumes zero Anthropic
   routine quota. Stop with Ctrl+C or `/daemon stop`.
   
   For true unattended background operation (machine sleeps, user away):
     /daemon start --remote    (uses RemoteTrigger, counts against 15/day cap)

Local execution safety

After approval of the campaign, finite budget and session limit, set localRunnerEnabled: true in daemon.json for the local runner. The default limit is 10 sessions; --max-sessions N requires a positive integer. A finite positive budget and valid estimatedSpend are required. The runner stops on failed execution and rechecks state before each spawn. Normal runtime permission checks remain enabled. The noninteractive environment variable alone does not authorize continuation. Remote starts leave this local opt-in disabled. See runner safety and migration.

Codex automation lane

In Codex, prefer a Codex Automation for durable unattended daemon ticks when available: node scripts/codex-automation.js plan --type daemon --command "/daemon tick" --cadence "<interval>" --target background-worktree --write. Use the returned prompt in the Codex app automation surface. Each run must still read and update .planning/daemon.json; Codex owns the scheduling, Citadel owns the budget/status gates and run log.

Opt-in routine flow — /daemon start --remote

Only when the user has explicitly passed --remote:

1. Before proceeding, confirm: "This will use Anthropic's RemoteTrigger, which counts against your 15 routine runs / 24h quota. A single overnight daemon can exhaust it. Continue? (y/N)"
2. If the user confirms, run the full Step 1-5 protocol below (including Step 3's trigger creation).

Commands

Protocol

/daemon start

Step 1: Validate prerequisites

1. Check .planning/ exists. If not: "No planning directory found. Run /do setup first."
2. Find the target campaign: if --campaign {slug} provided, read .planning/campaigns/{slug}.md; otherwise scan .planning/campaigns/ (excluding completed/) for files with status: active in frontmatter. No active campaign → "No active campaign. Start one with /archon first." Multiple active and no flag → list them, ask user to specify.
3. Verify the campaign has a Continuation State section (Archon knows where to resume)
4. Parse budget: default $50. --budget unlimited → set budget to Infinity, warn: "No budget cap. You will not be protected from runaway costs. Monitor usage at your Anthropic dashboard." --budget {N} → parse as number, must be > 0.
5. Parse cost-per-session: --cost-per-session {N} if provided; else the campaign's estimated_cost_per_loop frontmatter field if present (improve campaigns set this to 12); otherwise default $3. The auto-read prevents running an improve campaign on the $3 default designed for simple archon sessions (rationale: docs/DAEMON.md#cost-estimation).

Step 2: Check for existing daemon

Read .planning/daemon.json if it exists. If a daemon is already running (status: "running"): show its state (campaign, sessions completed, budget remaining) and ask "A daemon is already running. Stop it and start a new one?" Yes → run /daemon stop first, then continue. No → abort.

Step 3: Create triggers (remote flow only)

A. Chain trigger — one-shot, fires after cooldown, command: "/daemon tick". Save ID as chainTriggerId. B. Watchdog trigger — recurring, fires every --interval, command: "/daemon tick --watchdog". Save ID as watchdogTriggerId. Both use type: scheduled/recurring, project_path: {absolute project root}, description: "Daemon: {slug} tick/watchdog".

Step 4: Write state file

Write .planning/daemon.json:

{
  "status": "running",
  "campaignSlug": "{slug}",
  "budget": 50,
  "costPerSession": 3,
  "estimatedSpend": 0,
  "localRunnerEnabled": false,
  "sessionCount": 0,
  "interval": "30m",
  "cooldown": "60s",
  "chainTriggerId": "{id from step 3A}",
  "watchdogTriggerId": "{id from step 3B}",
  "startedAt": "{ISO timestamp}",
  "lastTickAt": null,
  "lastTickStatus": null,
  "stoppedAt": null,
  "stopReason": null,
  "log": []
}

Step 5: Log and confirm

Log daemon-start event with budget and interval. Output confirmation: campaign slug, budget (estimated sessions), cooldown, watchdog interval, state file path. Suggest /daemon status and /daemon stop.

/daemon stop

1. Read .planning/daemon.json. If missing or not running: "No daemon is running."
2. Delete both triggers (ignore failures — may already be cleaned up).
3. Update daemon.json: status: stopped, stoppedAt, stopReason: user.
4. Log daemon-stop event. Output: sessions completed, estimated spend, campaign status.

/daemon status

Output: status, campaign (slug + phase), sessions, budget (spent/cap/remaining), cost/session source, last tick (time + status), running duration, watchdog interval, state file path.

If paused-level-up: add instructions to review proposals at .planning/rubrics/{target}-proposals.md and set campaign status: active to resume. For improve campaigns: add loops completed/total, current level, last axis attacked.

/daemon log

Read .planning/daemon.json and output the log array, most recent first, as [{timestamp}] Session #{N}: {status} -- {summary} with a second line Phase: {phase} | Duration: {duration} | Est. cost: ${cost} (entry format: docs/DAEMON.md#daemonjson-reference). Show the last 20 entries. If more exist: "Showing last 20 of {total}. Full log in .planning/daemon.json"

/daemon tick

This is the heartbeat handler. It runs in a fresh Claude Code session spawned by the scheduler. It is not user-facing.

Step 1: Gate checks

1. Read .planning/daemon.json
2. Status gate: If status is not "running" and not "paused-level-up" -- exit silently. The daemon was stopped. If "paused-level-up": read the campaign file. If campaign status is now active (human approved the level-up): update daemon.json status: "running", clear pauseReason, log daemon-resume with reason level-up-approved, continue to Step 2. If still level-up-pending: exit silently (still waiting for human).
3. Lock gate: If lastTickAt is within the last 2 minutes and lastTickStatus is "running" -- another session is active. Exit silently.
4. Budget gate: If estimatedSpend >= budget -- stop the daemon: update daemon.json (status: "stopped", stopReason: "budget-exhausted"), delete both triggers, log daemon-stop with reason budget-exhausted, exit.
5. Campaign gate: Read the campaign file.
   • File does not exist, or status: completed, failed, or parked -- stop the daemon: update daemon.json (status: "stopped", stopReason: "no-active-work" for a missing file, "campaign-completed" / "campaign-failed" / "campaign-parked" for the matching status), delete both triggers, log daemon-stop with that reason, exit.
   • status: level-up-pending -- pause the daemon (do not stop): update daemon.json status: "paused-level-up", pauseReason: "Improve hit distribution saturation. Human approval required for level-up proposals." Do NOT delete triggers (the watchdog stays alive to detect when the human resumes). Log daemon-pause with reason level-up-pending. Append to daemon.json log: "Paused: level-up triggered. Approve proposals at .planning/rubrics/{target}-proposals.md and set campaign status to active to resume." Exit.

Step 2: Acquire lock

Update daemon.json: lastTickAt = current ISO timestamp, lastTickStatus: "running".

Step 3: Execute

Run /do continue -- routes to Archon, which reads the campaign's Continuation State and picks up where the last session left off. Archon works until the current phase completes (normal exit), context runs low and PreCompact fires (saves state, session can end), or an error parks the campaign.

Step 4: Record session

After /do continue returns (or the session is winding down):

1. Read the campaign file again to get updated status and phase
2. No-work gate: If the campaign status is completed, failed, parked, or the campaign file no longer exists -- stop the daemon immediately: update daemon.json (status: "stopped", stopReason: "no-active-work", stoppedAt: "{ISO timestamp}"), delete both triggers, log daemon-stop with reason no-active-work. Do NOT schedule the next tick. Exit after recording the session.
3. Update daemon.json: increment sessionCount, add costPerSession to estimatedSpend, set lastTickStatus: "completed", append a log entry with session, timestamp, status, phase, summary, and estimatedCost (JSON shape: docs/DAEMON.md#daemonjson-reference).
4. Run a safe memory consolidation pass when the session produced planning changes: node scripts/memory-compile.js compile. If it fails, record the failure in daemon.json log and continue shutdown or scheduling; memory compile failures must not create overlapping daemon ticks.

Step 5: Schedule next tick

Re-read daemon.json. If still running and estimatedSpend + costPerSession <= budget: create new chain trigger (one-shot, cooldown delay), update chainTriggerId. If budget would be exceeded: stop daemon (budget-exhausted), delete watchdog, log daemon-stop.

Step 6: Exit

Session ends cleanly. PreCompact hook saves campaign state. The next tick starts a fresh session with full context budget.