> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commanderplugin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Daemon Mode: Background Agent for Continuous Project Work

> Run CC Commander as a background agent that monitors your project, processes a task queue, and consolidates session knowledge without a terminal open.

Daemon Mode runs CC Commander as a background process that keeps working on your project even when you close your terminal. It operates on a tick loop, checking a task queue every 5 minutes, dispatching work to Claude, and periodically running a "dream" cycle to consolidate session knowledge. State is stored in `~/.claude/commander/` and persists across reboots.

## Starting and stopping the daemon

```bash theme={null}
ccc --daemon          # Start the daemon (runs in background)
ccc --daemon-stop     # Stop the daemon
```

When the daemon starts, it writes its PID to `~/.claude/commander/daemon.pid` and logs all activity to `~/.claude/commander/daemon-log.txt`. The log file rotates automatically at 1 MB.

## Managing the task queue

You interact with a running daemon by queuing tasks from any terminal:

```bash theme={null}
ccc --queue "fix login bug"       # Add a task to the queue
ccc --queue-list                  # Show all pending tasks and their status
```

Tasks are stored in a priority-based, file-backed queue. The daemon picks up the next task on each tick, dispatches it to Claude using the Opus model with up to 30 turns and a \$5 budget per task, and records the result back to the queue. Knowledge is extracted from each completed session and stored for future dispatches.

<Note>
  The daemon uses the same Intelligence Layer as interactive dispatches — complexity scoring, stack detection, and knowledge retrieval all run before each task is sent to Claude.
</Note>

## How the tick loop works

Every 5 minutes (by default), the daemon runs a tick:

<Steps>
  <Step title="Process the task queue">
    The daemon calls `queue.getNext()` to find the highest-priority pending task and marks it as running.
  </Step>

  <Step title="Check git status">
    If the working directory has more than 10 uncommitted changes, the daemon logs a warning. It does not commit automatically — that remains your responsibility.
  </Step>

  <Step title="Enforce the budget">
    Each tick has a time budget (15 seconds by default). If the tick takes longer than the budget before dispatching, the dispatch is skipped and logged.
  </Step>

  <Step title="Dispatch the task">
    The daemon calls `dispatchWithRetry` with the task, which handles rate limit waits, context overflow retries, and budget exceeded errors automatically.
  </Step>

  <Step title="Extract knowledge">
    After a task completes, the daemon extracts lessons (keywords, category, error patterns, success patterns) and stores them in `~/.claude/commander/` for future sessions.
  </Step>
</Steps>

## Dream mode

Once per hour (by default), the daemon runs a dream cycle instead of a tick. Dream mode consolidates the knowledge base: it aggregates lessons from completed sessions, calculates success rates, archives old entries, and surfaces improvement suggestions in the log.

```text theme={null}
[daemon] Dream: starting consolidation...
[daemon] Dream: 47 lessons, 89% success, $12.40 total cost, 3 archived
[daemon] Dream suggestion: JWT + httpOnly cookies pattern works reliably with Next.js middleware
```

## Customization flags

You can adjust the daemon's timing and budget when starting it:

| Flag               | Default     | What it controls                       |
| ------------------ | ----------- | -------------------------------------- |
| `--interval 120`   | 300 (5 min) | Tick interval in seconds               |
| `--tick-budget 30` | 15          | Time budget per tick action in seconds |
| `--dream 30`       | 60          | Dream cycle interval in minutes        |

```bash theme={null}
# Tick every 2 minutes, dream every 30 minutes
ccc --daemon --interval 120 --dream 30

# Tick every 5 minutes with a tighter action budget
ccc --daemon --tick-budget 10
```

## State files

All daemon state lives in `~/.claude/commander/`:

| File             | What it contains                                            |
| ---------------- | ----------------------------------------------------------- |
| `daemon.pid`     | PID of the running daemon process                           |
| `daemon-log.txt` | Full activity log (rotates at 1 MB to `daemon-log.txt.old`) |
| `queue.json`     | Task queue with status, priority, and results               |
| `state.json`     | User settings — name, level, cost ceiling, theme            |
| `knowledge/`     | Session lessons for the knowledge compounding engine        |
| `yolo-stop`      | Create this file to halt a Night Mode loop gracefully       |

<Warning>
  Do not delete `~/.claude/commander/` while the daemon is running. Stop it first with `ccc --daemon-stop`, then make any changes.
</Warning>

## Checking daemon status

The daemon status is visible from inside Claude Code:

```text theme={null}
/ccc daemon
```

This shows whether the daemon is running, the PID, the last tick time, and the current queue contents.

<Tip>
  Daemon Mode pairs well with Night Mode. Start an overnight YOLO build for complex features, and use the daemon queue for smaller incremental tasks — bug fixes, dependency updates, documentation — that should be processed when Claude has capacity.
</Tip>