Skip to main content
skill CX Codex

daemon — Claude Code skill: what it does, how to install

daemon keeps a Citadel campaign going by chaining Claude Code sessions one after another until the budget or phase runs out.

MIT ★ 937 updated 2026-11-05

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What daemon does

The skill drives the /daemon command set: start, stop, status, log, plus an internal tick heartbeat that fires the next session. Each run resumes the campaign from its Continuation State section, works until context gets low or the phase finishes, and queues the next session through either a local runner or RemoteTrigger.

By default /daemon start skips RemoteTrigger entirely and tells you to launch npm run daemon:local in another terminal, which costs nothing against Anthropic's quota. Adding --remote switches to RemoteTrigger, but that counts toward the account-wide cap of 15 routine runs per 24 hours, so the skill asks for explicit confirmation before using it since one overnight run can eat the whole quota and stall other routines on the same account.

Budget defaults to $50 and each session is estimated at $3, though an improve-type campaign pulls $12 instead if its estimated_cost_per_loop field is set. On Codex, for ticks that need to survive without anyone watching, the skill points to node scripts/codex-automation.js plan --type daemon --command "/daemon tick" with a chosen cadence rather than manual triggering.

What it helps with

  • run a Citadel campaign without staying at the keyboard
  • switch between a local runner and RemoteTrigger without blowing the account's routine quota
  • cap unattended session spending at a fixed dollar amount
  • pick up exactly where a session left off once context runs low
  • wire up scheduled daemon ticks inside Codex

Example prompts for the agent

  • Run /daemon start on the current campaign with a $30 budget
  • Check /daemon status for how many sessions have run so far
  • Stop the background loop with /daemon stop

How to install daemon

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill daemon -a claude-code

3Manually: put the files in place

~/.claude/skills/daemon/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/daemon/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about daemon

How do I install daemon in Claude Code?

Add the marketplace first with /plugin marketplace add SethGammon/Citadel, then run /plugin install citadel@citadel-local.

What does daemon do?

It chains Claude Code sessions so a Citadel campaign keeps progressing without a person restarting it each time, stopping once the budget or campaign phase is done.

Why doesn't /daemon start use RemoteTrigger right away?

RemoteTrigger counts against the account's shared cap of 15 routine runs per 24 hours, and a single overnight session can use it all up. So the default path runs a local npm run daemon:local loop instead, with RemoteTrigger only turned on via --remote after you confirm.

Source text

SKILL.md · MIT
---
name: daemon
license: MIT
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
trigger_keywords:
  - daemon
  - continuous
  - run overnight
  - keep running
  - 24/7
  - unattended
  - run autonomously
  - daemon start
  - daemon stop
  - daemon status
last-updated: 2026-11-04
---

# /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](../../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.** Leave `chainTriggerId` and `watchdogTriggerId` as `null` in the state file. Keep the confirmation focused on the state path, campaign, finite budget, session ceiling, and local start/stop instructions.
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`.

   ```

### 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](../../docs/ISSUE-278-SECURITY.md).

### 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. 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`:

```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.

### /daemon tick --watchdog

Same as `/daemon tick` but 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) and 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 reads `.planning/daemon.json`; if `status: running`, it checks the lock (no overlap), budget (can afford), and campaign (still active), and when all gates pass outputs `[daemon] Active daemon detected. Campaign: {slug}. Run: /do continue` — the agent sees this first and executes `/do continue`. RemoteTrigger's role is reduced to scheduling session starts; if it is unavailable, an OS cron job or manual restart achieves the same result (architecture: docs/DAEMON.md#how-it-works).

## 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
- For an explicitly requested remote start, both triggers (chain + watchdog) must be created; if either fails, abort and clean up. Local starts keep both trigger IDs null.
- 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

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set55

The whole set →
learn learn turns completed campaigns or evolve cycles into structured project wiki entries. Use it to carry decisions and recurring patterns into future sessions. CX Codex +1 ★ 937repo stars dashboard dashboard is a Claude Code skill that shows harness state, including campaigns, agent sessions, telemetry, and queues. Run it with /dashboard, /do status, or a request to show activity. CX Codex +1 ★ 937repo stars evolve evolve — a skill for Claude Code and Codex that drives iterative code advancement by forming hypotheses about why scores stall, validating them with scout agents, and coordinating targeted fixes across cycles. CX Codex +1 ★ 937repo stars improve The skill scores a target against a rubric, picks one area to work on, then checks the result. Use it for repeatable improvement cycles rather than a one-off bug fix. CX Codex +1 ★ 937repo stars setup setup — a skill for Claude Code and Codex that configures your project on first run: installs hooks, detects your tech stack, generates harness.json, and demonstrates Citadel live on your code. CX Codex +1 ★ 937repo stars archon archon — an autonomous agent that breaks large projects into phases, delegates to sub-agents, and runs campaigns across sessions while preserving state and enforcing quality gates. CX Codex +1 ★ 937repo stars do Looks at what you typed and decides where it belongs — a direct command, a skill, or one of Citadel's orchestrators. Useful when you don't want to pick the tool yourself. CX Codex +1 ★ 937repo stars fleet fleet is a Claude Code skill that splits large tasks into independent streams and runs them in waves of up to three agents across isolated git worktrees. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open