Skip to main content
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.
Use this page when Charlie or another agent is creating a new daemon file or improving an existing one. Use DAEMON.md reference for the exact contract. Use this page to make the file good, not just valid.

​
The default stance

Write the narrowest daemon that can do the job. A good daemon file is:
  • narrow
  • explicit
  • concise
  • predictable
  • easy to review and iterate on
Start with:
  • one purpose
  • usually 2–3 routines
  • clear deny guidance
  • only the body sections that materially improve behavior
Do not write a broad, impressive-looking daemon that is hard to trust.

​
Frontmatter vs body

Use frontmatter for the concise declarative contract:
  • identity
  • purpose
  • wake conditions
  • core routines
  • hard prohibitions
  • schedule
Use the body for operating guidance that makes behavior more consistent:
  • policy
  • output format
  • limits
  • scope
  • priority
  • thresholds
  • conventions
  • coordination
  • ignore patterns
  • examples
Authors set watch and/or schedule. The runtime derives activation mode from those fields; do not add activationMode as a frontmatter field. A daemon must include at least one of watch or schedule. If something is a stable authored field, it belongs in frontmatter. If something is operating guidance or judgment-shaping prose, it belongs in the body.

​
Create mode

When creating a new daemon:

​
1. Write the purpose as outcome, not mechanics

A strong purpose says what the daemon exists to achieve. Good:
  • “Keeps repository docs current and easy to discover.”
Weak:
  • “Scans for stale markdown files and suggests updates.”
The daemon’s purpose should make sense as the role’s job statement.

​
2. Choose the wake model

Use watch when the daemon should react to discrete events. Use schedule when the daemon should wake on time and survey what needs attention. Use both only when the same daemon role genuinely needs both immediate reaction and periodic review. A daemon must include at least one of watch or schedule.

​
3. Write a small number of concrete routines

Routines should be concrete, finite operations. Good routines are things you can tell whether the daemon did or did not do. Good:
  • “propose clearer PR titles and summaries”
  • “identify missing test evidence in PR descriptions”
  • “suggest focused follow-up tasks when context is incomplete”
Weak:
  • “help with pull requests”
  • “improve code quality”
  • “manage the repo”
As a default, start with 2–3 routines.

​
4. Add deny rules for adjacent risks

The most important deny rules are not random safety slogans. They are the risky actions the daemon might reasonably attempt as a natural extension of its routines. Examples from the authoring guidance:
  • “Do not merge pull requests”
  • “Do not approve pull requests on behalf of humans”
  • “Do not push commits directly to protected branches”
  • “Do not delete files or directories”
If a daemon can plausibly take a risky shortcut, decide explicitly whether to deny it.

​
5. Add body guidance only where it improves behavior

The body is not decorative. Use it to make the daemon more predictable. A small daemon does not need every possible section. Add sections when they materially improve consistency, reduce noise, or make outputs easier to review.

​
Edit mode

Editing is not the same as creation. When editing an existing daemon:

​
1. Read before rewriting

Inspect the current daemon file first. Preserve:
  • the daemon’s identity
  • the intended role
  • any guidance that is already working
Do not rewrite a daemon from scratch unless the role itself is wrong or the file is too weak to repair incrementally.

​
2. Diagnose the failure mode

Before changing the file, decide whether the problem is:
  • the daemon wakes for the wrong things
  • the daemon wakes correctly but acts too broadly
  • the daemon lacks enough operating guidance
  • the daemon is missing limits
  • the daemon is over-constrained and too passive
Different problems require different edits.

​
3. Tighten vague watch conditions

Turn state-based or catch-all watch entries into specific, observable events. Prefer edits like:
  • “when a pull request is opened”
  • “when a maintainer comments “/daemon help” in a PR”
  • “when files matching docs/**/*.md are changed”
Over vague entries like:
  • “when the repo needs attention”
  • “when code changes”
Keep the daemon’s role the same. Make the wake logic more precise, not broader.

​
4. Narrow or split broad routines

If one routine covers several jobs, split it. If a routine sounds like an abstract responsibility, rewrite it as a concrete operation. Prefer the smallest set of routines that still captures the daemon’s real job.

​
5. Add missing deny rules

Look for risky shortcuts the daemon might naturally attempt as the fastest way to satisfy its routines. Add deny rules for those nearby risks rather than generic safety slogans.

​
6. Reduce noise without changing the daemon’s identity

If the daemon is doing the right kind of work but too often, too broadly, or too noisily, do not change the purpose first. Instead, tighten the parts that bound behavior:
  • add Limits to control volume or pacing
  • add Scope or Ignore patterns to filter surfaces early
  • add Coordination to avoid overlap with humans or other daemons
This keeps the daemon’s role intact while making repeated activations more trustworthy.

​
7. Prefer targeted improvement over full rewrite

Prefer the smallest change that clearly improves behavior. Rewrite only when the file’s role definition is fundamentally wrong or the current file is too inconsistent to repair incrementally.

​
How to write strong frontmatter

​
id

id must exactly match the daemon ID and path slug. Good:
  • pr-mergeability
Bad:
  • PR Mergeability

​
purpose

Write the intended outcome, not the mechanics. Good:
  • “Keeps repository docs current and easy to discover.”
Bad:
  • “Scans for stale markdown files and suggests updates.”

​
watch

Each watch entry should describe a specific, observable event. Good:
  • “when a pull request is opened”
  • “when a maintainer comments “/daemon help” in a PR”
  • “when files matching docs/**/*.md are changed”
Weak:
  • “when code quality is low”
  • “when the repo needs attention”
  • “when code changes”
Use watch entries that describe something the system can observe as an event. Watch matching is semantic rather than deterministic rule matching, so concrete observable phrasing is more reliable than vague state-based phrasing. Current watch behavior is GitHub-first; Slack and Linear watch support is coming soon.

​
routines

Each routine should be a concrete, finite operation. Good:
  • “propose clearer PR titles and summaries”
  • “identify missing test evidence in PR descriptions”
  • “suggest focused follow-up tasks when context is incomplete”
Weak:
  • “help with pull requests”
  • “improve code quality”
  • “manage the repo”

​
deny

Write deny rules for the most important nearby risks. If a daemon might reasonably try a risky action because it seems like the fastest path to its goal, decide explicitly whether to deny that action.

​
schedule

Use schedule for timer-based wakes. Schedules use standard five-field cron in UTC. This is for time-based survey or follow-up work, not for describing event conditions. The runtime may derive activation-mode labels from watch and schedule. Do not write activationMode as a frontmatter field. Examples:
  • 0 9 * * * — daily at 09:00 UTC
  • 0 */6 * * * — every 6 hours
  • 30 14 * * 1-5 — weekdays at 14:30 UTC

​
How to write strong body guidance

Use only the sections that materially improve behavior.

​
Policy

Use when the daemon needs decision rules, standards, or team opinions about what good looks like.

​
Output format

Use when the daemon produces comments, reports, or other structured visible output and you want consistency.

​
Limits

Use when the daemon could otherwise create too much output or work. Limits can control:
  • batch size
  • rate
  • pacing relative to human capacity

​
Scope

Use when the daemon should only pay attention to specific parts of the repo, workflow, or surface.

​
Priority

Use when several valid targets may compete for the daemon’s attention.

​
Thresholds

Use when numeric or qualitative cutoffs should affect detection or action.

​
Conventions

Use when the team has norms the daemon should follow.

​
Coordination

Use when the daemon might overlap with human work or other daemons.

​
Ignore patterns

Use when specific files, directories, labels, authors, or event patterns should be skipped entirely.

​
Examples

Use when the daemon’s job includes subjective judgment and concrete examples will improve consistency.

​
What to include only when it matters

Not every daemon needs every body section. Add these only when they materially improve behavior:
  • Add Limits when the daemon could otherwise create more work or noise than the team can absorb.
  • Add Output format when the daemon produces comments, reports, or other recurring visible output and consistency matters.
  • Add Coordination when overlap with humans or other daemons is plausible.
  • Add Scope or Ignore patterns when the daemon listens to a high-volume surface or only part of the repo or workflow is relevant.
  • Add Examples when the daemon’s job depends on subjective judgment or style consistency.

​
Common mistakes

These are the most common daemon-file mistakes:

​
Vague watch conditions

A watch entry must describe an event, not a general state.

​
Unbounded routines

If you cannot tell whether the daemon completed the routine, the routine is too vague.

​
Missing deny rules

If a risky nearby action is plausible, decide explicitly whether to deny it.

​
No limits where output can sprawl

A daemon without limits can produce more work or noise than the team can absorb.

​
Invented frontmatter fields

Do not invent fields. Use the authored fields from DAEMON.md reference.

​
Treating body headings like schema

Headings such as Policy, Limits, or Scope belong in the markdown body, not as new frontmatter fields.

​
Generic filler in the body

If a section does not change what the daemon will actually do, tighten it or remove it.

​
Critique rubric

Use this rubric when reviewing a draft daemon file.

​
Purpose

  • Is the purpose written as outcome, not mechanics?
  • Is the role narrow enough to explain in one sentence?

​
Wake logic

  • Are watch conditions actual events?
  • Does the schedule serve a real time-based need?
  • Is the daemon using both watch and schedule only when both are justified?
  • If the daemon is noisy, can the wake logic be made more specific without changing the role?

​
Routines

  • Are routines concrete and finite?
  • Would a human be able to tell whether the daemon did them?
  • Does each routine describe one kind of operation, or should any be split?

​
Constraints

  • Are the main adjacent risks denied?
  • Are limits present when the daemon could create noise?
  • Would scope, coordination, or ignore patterns make the daemon more predictable?

​
Body guidance

  • Does the body add real behavioral guidance?
  • Are the sections specific, or are they generic filler?

​
Overall

  • Is this the narrowest useful daemon?
  • If it is noisy, can you fix that with tighter watch logic, routines, or body guidance before changing the purpose?
  • Would you trust this file to be activated repeatedly?
If the answer is “no” to any of those, edit the file before rollout.

​
How to use examples while writing or editing

Start with the nearest example daemon from the examples repo README. Use examples to copy:
  • structure
  • level of specificity
  • the kind of constraints that belong with a daemon role
Do not copy:
  • irrelevant routines
  • irrelevant deny rules
  • irrelevant scope or limits
  • team-specific conventions that do not apply here
A good example gives you the right shape. It does not remove the need to adapt the daemon to the repo’s real role.