daemon

name	daemon
description	Continuous autonomous operation mode. Keeps campaigns running 24/7 by chaining Claude Code sessions via RemoteTrigger. Each session picks up from the campaign's continuation state, works until context runs low or the phase completes, then schedules the next session. Auto-stops on campaign completion or budget exhaustion. The thing that makes Citadel run overnight.
user-invocable	true
auto-trigger	false
last-updated	"2026-03-28T00:00:00.000Z"

/daemon -- Continuous Autonomous Operation

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:

   Daemon state created: .planning/daemon.json
     Campaign:  {slug}
     Budget:    ${N}
   
   To start the tick loop, run in a separate terminal:
     npm run daemon:local
   
   Leave that terminal open. It spawns `claude -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)
   

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

Command	Behavior
/daemon start	Default: create state file, prompt user to run npm run daemon:local (zero routine cost)
/daemon start --remote	Use RemoteTrigger instead (counts against 15/day routine quota — requires confirmation)
/daemon start --campaign {slug}	Target a specific campaign
/daemon start --budget {N}	Set budget cap in dollars (default: $50)
/daemon start --budget unlimited	Explicitly disable budget cap
/daemon start --interval {N}m	Set watchdog interval (default: 30m)
/daemon start --cooldown {N}s	Set delay between sessions (default: 60s)
/daemon start --cost-per-session {N}	Override per-session cost estimate (default: $3)
/daemon stop	Stop the daemon, tear down triggers
/daemon status	Show daemon state, session count, budget remaining
/daemon log	Show recent daemon session history
/daemon tick	Internal: heartbeat handler fired by triggers. Not user-facing.

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
   • If no active campaign found: "No active campaign. Start one with /archon first."
   • If multiple active campaigns and no --campaign 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
   • If --budget unlimited: set budget to Infinity, warn: "No budget cap. You will not be protected from runaway costs. Monitor usage at your Anthropic dashboard."
   • If --budget {N}: parse as number, must be > 0
5. Parse cost-per-session:
   • If --cost-per-session {N} provided: use that value
   • If not provided AND the campaign has an estimated_cost_per_loop field in frontmatter (improve campaigns set this to 12): use that value
   • Otherwise: default $3
   • This auto-read prevents the common mistake of running an improve campaign (which spawns 3 evaluator agents + attack + verify per loop) with the $3 default designed for simple archon sessions

Step 2: Check for existing daemon

1. Read .planning/daemon.json if it exists
2. If a daemon is already running (status: "running"):
   • Show its state: campaign, sessions completed, budget remaining
   • Ask: "A daemon is already running. Stop it and start a new one?"
   • If yes: run /daemon stop first, then continue
   • If no: abort

Step 3: Create triggers

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,
  "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

1. Read .planning/daemon.json
2. Output the log array, most recent first, formatted as:

   [{timestamp}] Session #{N}: {status} -- {summary}
     Phase: {phase} | Duration: {duration} | Est. cost: ${cost}
   

3. 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 RemoteTrigger. 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 status is "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, and continue to Step 2 (acquire lock). If campaign is 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 (RemoteTrigger delete)
   • Log: daemon-stop with reason budget-exhausted
   • Exit.
5. Campaign gate: Read the campaign file.
   • If the campaign file does not exist -- stop the daemon:
     • Update daemon.json: status: "stopped", stopReason: "no-active-work"
     • Delete both triggers
     • Log: daemon-stop with reason no-active-work
     • Exit.
   • If status: completed or status: failed -- stop the daemon:
     • Update daemon.json: status: "stopped", stopReason: "campaign-{status}"
     • Delete both triggers
     • Log: daemon-stop with reason campaign-completed or campaign-failed
     • Exit.
   • If status: parked -- stop the daemon:
     • Same as above with stopReason: "campaign-parked"
     • Exit.
   • If 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 -- this routes to Archon, which reads the campaign's Continuation State and picks up where the last session left off.

Archon will work until:

• The current phase completes (normal exit)
• Context runs low and PreCompact fires (saves state, session can end)
• 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 (RemoteTrigger delete)
   • Log: daemon-stop with reason no-active-work
   • Do NOT schedule the next tick. Exit after recording the session.

3. Update daemon.json:

   • sessionCount: increment by 1
   • estimatedSpend: add costPerSession
   • lastTickStatus: "completed"
   • Append to log array:

     {
       "session": {sessionCount},
       "timestamp": "{ISO timestamp}",
       "status": "completed",
       "phase": "{current_phase}",
       "summary": "{brief description of what happened}",
       "estimatedCost": {costPerSession}
     }
     

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 will start a fresh session with full context budget.

---

/daemon tick --watchdog

Same as /daemon tick but with an additional check at Step 1:

After the standard gate checks pass, check whether the chain is alive:

• Read lastTickAt from daemon.json
• If lastTickAt is more than 2 * interval ago AND lastTickStatus is not "running":
  • The chain died. Log: "Watchdog: chain appears dead. Last tick at {lastTickAt}. Restarting chain."
  • Proceed with Step 2 onwards (this watchdog tick becomes a chain tick)
  • Schedule the next chain tick in Step 5
• If lastTickAt is recent (within 2 * interval): the chain is healthy. Exit silently.

---

SessionStart Hook Bridge (Primary Bootstrap)

The daemon's primary continuation mechanism is the init-project.js SessionStart hook, not RemoteTrigger prompt injection. On every session start, the hook:

1. Reads .planning/daemon.json
2. If status: running: checks the lock (no overlap), budget (can afford), and campaign (still active)
3. If all gates pass: outputs [daemon] Active daemon detected. Campaign: {slug}. Run: /do continue
4. The agent sees this message first and executes /do continue

RemoteTrigger's role is reduced to scheduling session starts. The hook handles everything else. If RemoteTrigger is unavailable, an OS cron job or manual restart achieves the same result.

---

Budget Tracking

Primary: Read latest entry from .planning/telemetry/session-costs.jsonl (written by session-end hook) for real cost. Use override_cost if present, else estimated_cost.

Fallback: costPerSession flat estimate (default $3). Each tick adds it to estimatedSpend.

Stop when estimatedSpend >= budget or estimatedSpend + costPerSession > budget (preemptive).

Overrides: --budget {N} | --budget unlimited (explicit, warns) | --cost-per-session {N}

---

Fringe Cases

• RemoteTrigger unavailable: SessionStart hook bridge still works. Suggest OS cron: */30 * * * * cd ~/project && claude -p '/do continue'
• No .planning/: "Run /do setup first."
• Campaign has no Continuation State: run /archon once interactively to establish it.
• daemon.json corrupted: treat as no daemon running; /daemon start fresh.
• Session crashes without next tick: watchdog restarts chain after 2 * interval.
• Multiple daemons: one per project. Block with "daemon already running" prompt.
• /daemon tick called manually: works, gate checks apply. Warn it's internal.
• Budget exhausted: stop, log "Budget exhausted. Restart with --budget {higher}."
• Level-up during run: detect level-up-pending, set paused-level-up, keep watchdog alive for human-resume detection.
• Campaign completes mid-session: no-work gate (Step 4) catches it, stops daemon.
• Idle loop bug (campaign done but daemon still running): three layers prevent it — campaign gate (Step 1), no-work gate (Step 4), /do Tier 1 stop. All write stopReason: no-active-work.

---

Contextual Gates

Disclosure

Always disclose, regardless of trust level:

• "Starting continuous mode on campaign {slug}. Budget: ${N} (~{sessions} sessions at ${cost}/session). Sessions restart automatically until done or budget exhausted."
• For unlimited budget: "WARNING: No budget cap. Sessions will continue until the campaign completes or you run /daemon stop."

Reversibility

• Amber: Standard daemon with budget cap -- stop with /daemon stop, no work is lost
• Red: Daemon with --budget unlimited -- no automatic cost protection

Red actions (unlimited budget) require explicit confirmation at ALL trust levels.

Proportionality

Before starting, verify daemon is warranted:

• If campaign has only 1 remaining phase: suggest running it directly instead
• If estimated sessions <= 2: suggest manual continuation instead
• If campaign is type improve and no rubric exists: block -- rubric requires human approval first

Trust Gating

Read trust level from harness.json:

• Novice (0-4 sessions): Block daemon activation entirely. Output: "Daemon mode requires familiarity with the harness. Complete a few sessions first, then daemon will be available."
• Familiar (5-19 sessions): Allow with full disclosure and explicit confirmation.
• Trusted (20+ sessions): Allow with cost-only confirmation.

Quality Gates

• Budget cap MUST be set (default $50, explicit unlimited to bypass)
• Daemon state file MUST be written before any triggers are created
• Both triggers (chain + watchdog) must be created; if either fails, abort and clean up
• Every tick must update daemon.json BEFORE scheduling the next tick
• Campaign must have Continuation State before daemon can start
• Lock mechanism must prevent overlapping sessions
• Watchdog must detect and recover from dead chains
• Stop must clean up ALL triggers (no orphaned triggers)

Exit Protocol

• start: confirmation output, no HANDOFF
• stop: stop summary, no HANDOFF
• tick: no user output (headless); updates daemon.json, schedules or stops
• status/log: output requested info
• On error: actionable message, clean up any dangling triggers before exiting