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

# Daemons

> Understand what Charlie daemons are, how they wake, and how DAEMON.md controls behavior.

<Tip>
  **Human readers:** the fastest way to get started with daemons is to work directly with Charlie.

  **Charlie can help you** suggest where to start and add your first daemon. Use the prompts below to ask Charlie in Slack, GitHub, or Linear.
</Tip>

<CodeGroup>
  ```markdown Learn about daemons theme={null}
  Explain what daemons are and how they work.
  ```

  ```markdown Daemon use cases theme={null}
  What are some use cases for daemons?
  Which would you recommend starting with?
  ```

  ```markdown Add a daemon theme={null}
  Open a PR to add a simple daemon to my repo.
  Explain what the daemon does and why you think it's a good place to start.
  ```
</CodeGroup>

***

Daemons are repo-defined operating roles for Charlie.

They give recurring operational debt an explicit owner instead of leaving it to ad hoc cleanup.

A daemon lives at:

`.agents/daemons/<daemon-id>/DAEMON.md`

The daemon file tells Charlie:

* its `purpose`
* what `watch` conditions or `schedule` can wake it
* what `routines` it should perform when it wakes
* what `deny` rules tell it not to do
* any additional operating guidance in the markdown body

## Start here

If you are a human reader, the intended workflow is to work with Charlie. Ask Charlie to:

* explain what daemons are
* explain how to use daemons
* recommend which daemons to add
* create a new daemon file
* edit an existing daemon file
* help you test and iterate safely

For the docs path, use the pages listed in **Where to go next** below.

## Use the daemon CLI

Use the daemon CLI when you want the quickest path to browse examples, inspect an example before adapting it, scaffold a draft into a repository, or validate local daemon files.

```bash theme={null}
bunx @charlie-labs/daemons --help
bunx @charlie-labs/daemons list
bunx @charlie-labs/daemons show pr-metadata
bunx @charlie-labs/daemons add pr-metadata --dry-run
bunx @charlie-labs/daemons validate --all
```

`list` and `show` are read-only browsing commands. `add --dry-run` previews the files that would be written, and `validate --all` checks local `.agents/daemons/**/DAEMON.md` files against the runtime file contract.

Scaffolding writes draft files only. A scaffolded daemon does not become eligible for live activations until the change is merged to the repository default branch and Charlie ingests that merged version.

## What daemons are

A daemon is a persistent role definition for recurring, bounded maintenance or operational work.

Teams use daemons when there is ongoing maintenance or operational judgment that should be owned explicitly instead of handled ad hoc.

Across activations, daemons can leverage prior activation logs to maintain state. Dedicated daemon memory is coming soon.

## What daemons are not

A Charlie daemon is different from:

* **Unix daemons:** a Charlie daemon is a repo-authored operating role, not a long-running OS process.
* **Cron jobs:** a Charlie daemon is not just fixed predetermined steps on a timer.
* **GitHub Actions:** a Charlie daemon is not a CI/workflow file tied to one pipeline.
* **Fixed-rule bots:** watch matching is semantic rather than deterministic.
* **Open-ended prompts:** a Charlie daemon is bounded by repo-local policy, `routines`, `deny`, and wake conditions.

## How daemons work today

Today, each activation follows a wake/execute model:

1. the daemon wakes because `watch` matched or `schedule` fired
2. context from past activations of the daemon is loaded
3. Charlie executes the daemon’s routines within daemon constraints
4. the activation completes

Supported wake sources are:

* routed GitHub events
* routed Linear events, including issue creation, issue comments, Charlie issue mentions, and issues assigned to Charlie
* routed Slack events, including mentions and thread replies, channel messages, and DMs
* scheduled wakes from the daemon’s `schedule` field

For GitHub, event-driven activation uses the repo-scoped GitHub App installation. For Linear, it requires a connected Linear workspace and the issue's Linear team mapped to a repo with daemon inventory. For Slack, it requires a connected Slack workspace mapped to a repo with daemon inventory. Write `watch` around observable GitHub, Linear, or Slack events; use execution-time policy for derived state that requires API queries or analysis.

Schedule-driven daemon activation uses the daemon’s `schedule` field when present as a standard five-field cron expression.

## `DAEMON.md` is the control surface

`DAEMON.md` is the authored control surface for a daemon.

The file has two parts:

* YAML frontmatter for the formal contract
* a markdown body for operating guidance

The frontmatter contains the authored fields:

* `id`
* `purpose`
* `watch`
* `routines`
* `deny`
* `schedule`

Minimum validity constraints:

* `id`, `purpose`, and `routines` are required.
* At least one of `watch` or `schedule` is required.

The body is freeform markdown. Use it for the operating rules that make the daemon consistent, such as:

* decision policy
* limits
* communication behavior
* verification
* freshness

Those headings are conventions in the body, not extra frontmatter schema.

Charlie treats the attached daemon file as the daemon’s primary role policy for each activation.

## Wake model

A daemon can be:

* watch-driven
* schedule-driven
* both

`watch` describes event conditions that can wake the daemon.

`watch` explains why a daemon wakes; it does not by itself authorize mutation.

`schedule` describes time-based wakes using a standard five-field cron expression.

If both are present, the daemon can wake from either path.

At runtime, Charlie may refer to the daemon as:

* Watch-only
* Schedule-only
* Hybrid

Those are runtime-derived labels. Do not author them as frontmatter fields.

## Key terms

* **daemon**: a repo-defined Charlie role for recurring maintenance or operational work
* **daemon ID**: the canonical identifier, represented by the directory name and required `id` field
* **daemon file**: the `DAEMON.md` file that defines the role
* **frontmatter**: the YAML contract at the top of the file
* **body**: the markdown guidance below the frontmatter
* **wake / activation**: one execution caused by an event or schedule
* **wake context**: the event or schedule reason the daemon woke for this activation
* **watch**: event conditions that can wake the daemon
* **routines**: the concrete operations the daemon performs when it wakes
* **deny**: things the daemon must not do
* **schedule**: timer-based wake configuration
* **native surfaces**: the systems where teams already review and act on daemon output, such as GitHub, Linear, and Slack

## Where to go next

* Read [Choosing daemons](/daemons/choosing-daemons) when deciding what daemon roles a team or repo should have.
* Read [Writing and editing `DAEMON.md`](/daemons/writing-and-editing-daemon-md) when creating a new daemon or improving an existing one.
* Use the [Review Checklist](/daemons/review-checklist) when reviewing daemon-file changes before merge.
* Read [Testing and iterating on daemons](/daemons/testing-and-iterating-on-daemons) before broad rollout.
* Read [`DAEMON.md` reference](/daemons/daemon-md-reference) when you need the exact file contract.
* Use the daemon CLI for the quick path to browse examples and validate local daemon files. Start with `bunx @charlie-labs/daemons list`, `bunx @charlie-labs/daemons show <example-id>`, and `bunx @charlie-labs/daemons validate --all`.
* Use the examples repo for concrete reference patterns, but start with its [README.md](https://github.com/charlie-labs/daemons/blob/master/README.md) and treat the examples as patterns to adapt, not as files to copy blindly.