Skip to main content

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.

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.
Explain what daemons are and how they work.
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. 
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 when deciding what daemon roles a team or repo should have.
  • Read Writing and editing DAEMON.md when creating a new daemon or improving an existing one.
  • Read DAEMON.md reference when you need the exact file contract.
  • Read Testing and iterating on daemons before broad rollout.
  • 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 and treat the examples as patterns to adapt, not as files to copy blindly.