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
watchconditions orschedulecan wake it - what
routinesit should perform when it wakes - what
denyrules 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
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:- the daemon wakes because
watchmatched orschedulefired - context from past activations of the daemon is loaded
- Charlie executes the daemon’s routines within daemon constraints
- the activation completes
watch matching is semantic rather than deterministic.
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
idpurposewatchroutinesdenyschedule
id,purpose, androutinesare required.- At least one of
watchorscheduleis required.
- policy
- limits
- scope
Wake model
A daemon can be:- watch-driven
- schedule-driven
- both
watch describes event conditions that can wake the daemon.
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
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
idfield - daemon file: the
DAEMON.mdfile 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 when deciding what daemon roles a team or repo should have.
- Read Writing and editing
DAEMON.mdwhen creating a new daemon or improving an existing one. - Read
DAEMON.mdreference when you need the exact file contract. - Read Testing and iterating on daemons before broad rollout.
- Use the examples repo for concrete reference patterns, but start with its README.md and treat the examples as patterns to adapt, not as files to copy blindly.