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.
Before choosing daemon roles, read Daemons. In this docs set, a daemon is a repo-defined operating role for Charlie, authored in .agents/daemons/<daemon-id>/DAEMON.md. That is not the same thing as a Unix daemon, a cron job, a GitHub Action, or a generic background agent. Use this page when Charlie or a human is deciding what daemon roles a team or repo should have. This page is about choosing the right daemon, not about the exact file format. For the file contract, read DAEMON.md reference. For how to write or edit a file, read Writing and editing DAEMON.md.

​
How to identify daemon opportunities

Do not start by asking, “What clever daemon could we build here?” Start by asking:
  • What recurring maintenance or operational work is happening here?
  • What recurring maintenance or operational work is not happening, but should be?
  • What low-grade operational debt is accumulating because nobody consistently owns it?
Daemons are a good fit when the work is recurring, bounded, and worth doing continuously.

​
Selection heuristics Charlie should apply

When choosing candidate roles, Charlie should usually:
  • prioritize the most repetitive and under-owned maintenance work
  • prefer narrow roles with obvious activation conditions
  • prefer daemon shapes that produce legible output on native surfaces
“Obvious activation conditions” means concrete observable evidence: a PR opened, a review submitted, a file path changed, a stale-item threshold crossed, or a recurring survey on a schedule. It does not mean vague intent like “when the repo needs help.” If a proposed role is broad, hard to wake reliably, or hard to review where the team already works, it is probably not the right first daemon.

​
What makes a good daemon candidate

A good daemon candidate is:
  • recurring: the work comes up repeatedly
  • bounded: the role can be described clearly enough to know what is in and out of scope
  • observable: there are events, schedules, or state changes that can wake the daemon
  • reviewable: the daemon’s outputs can be seen and judged on native surfaces
  • valuable even when done incrementally: each activation can do a small amount of useful work
A strong first daemon is usually narrow. It does one ongoing job well and escalates or skips what falls outside that job. Scheduled daemon roles are strongest when each activation can create value on its own. Frame them as recurring surveys, checks, or reconciliation passes, not as open-ended background ambition. Activations should stay bounded, but runs can still use context from prior run logs.

​
Daemon or one-off Charlie task?

Use a daemon when the same bounded role should wake repeatedly and add value over time. Use a normal Charlie task when:
  • the work has a clear finish line
  • the request is specific to one temporary push, investigation, or project moment
  • the work depends heavily on transient human context
  • the work is useful now but not worth maintaining as an ongoing role
A useful test is: if this were handled well once, would we still want the same role to keep waking later? If yes, it may be a daemon. If no, it is probably a one-off Charlie task.

​
What not to daemonize

Do not daemonize work that is:
  • one-off
  • vague
  • broad enough to read like “improve everything”
  • dependent on hidden human context that the daemon cannot reliably infer
  • dependent on continuously running process semantics instead of bounded activations with clear wake signals
  • too risky to act on without strong escalation boundaries
  • only useful as an ad hoc investigation or project-specific push
If the work is better framed as one normal task for Charlie, use a normal task instead of a daemon.

​
Use-case families

The families below are representative, not exhaustive. They are broader than the current public example set. Use the nearest example as a pattern anchor, not as a boundary on what is allowed.

​
PR maintenance

Use a daemon when PRs routinely:
  • go stale
  • lose mergeability
  • have weak titles or descriptions
  • miss expected evidence
  • accumulate fixable hygiene issues that nobody owns
  • carry review feedback that needs ongoing triage
Example daemon files: pr-metadata, pr-review-triage, pr-mergeability.

​
Issue or project-graph hygiene

Use a daemon when:
  • issue status drifts from reality
  • labels are missing or inconsistent
  • PRs and issues are not linked correctly
  • completed work is not being closed or updated
  • project metadata is expected to stay structured, but nobody maintains it

​
Documentation freshness

Use a daemon when:
  • docs drift behind implementation
  • README and setup instructions become unreliable
  • operational docs or runbooks rot quietly
  • documentation maintenance is clearly needed but never prioritized

​
Dependency or codebase maintenance

Use a daemon when:
  • dependencies age without review
  • low-risk mechanical fixes pile up
  • dead code or scaffolding accumulates
  • low-grade maintenance work exists but nobody owns it continuously

​
Bug or error triage

Use a daemon when:
  • bug reports or alerts pile up without triage
  • repeated issues disappear into noise
  • someone needs to maintain a structured view of what deserves human attention
  • duplicates, conflicts, or stale feedback regularly waste time

​
Scheduled surveys, checks, or reports

Use a daemon when:
  • the most useful work is not tied to one event
  • you need recurring review of a surface
  • the job is “notice what needs attention on a schedule” rather than “react immediately to one signal”
  • the best role is periodic reconciliation, ranking, or reporting

​
When to choose watch, schedule, or both

Choose watch when the daemon should react to a discrete event. Choose schedule when the daemon should wake on time, survey a scope, and decide what matters now. Choose both when the daemon needs:
  • immediate reaction to some events
  • plus periodic review for issues that may not emit a useful event
Use watch for event-driven work. Use schedule for time-driven work. Use both only when both wake postures materially help the same daemon role. Today, signal-driven daemon inference runs only for GitHub signals. If a proposed role mainly depends on Slack or Linear event triggers, prefer schedule-driven selection for now, or a hybrid whose watch path can ride on GitHub signals where that makes sense.

​
How to scope a daemon well

Keep one daemon when:
  • the work serves one narrow purpose
  • the wake logic is closely related
  • the risk profile is similar
  • the outputs belong on the same native surfaces
Split into multiple daemons when:
  • the role is trying to do too many unrelated things
  • some routines need very different wake logic
  • some routines need very different limits or escalation boundaries
  • some routines would be easier to reason about as smaller roles
  • different kinds of output belong on different native surfaces
When in doubt, split broad ideas into smaller daemon candidates and start with the narrowest useful version. A good first daemon is usually narrower than the daemon you might eventually want.

​
How to choose the first daemon

Do not start with the most ambitious daemon. Start with the recurring maintenance work that is:
  • clearly under-owned
  • high-friction for the team when neglected
  • easy to bound
  • easy to review on native surfaces
  • likely to create value without high-risk side effects
  • likely to produce signal rather than noise
In practice, that usually means starting with one obvious maintenance role rather than a “repo caretaker” that tries to own everything.

​
Value versus noise

A daemon is more likely to add value when:
  • its wake conditions are concrete
  • its outputs appear where the team already reviews that kind of work
  • its actions are easy to verify
  • its scope is narrow enough to explain in one sentence
  • each activation can do a small amount of useful work without broad wandering
Warning signs that a daemon will mostly create noise:
  • the wake condition is vague
  • the role touches too many unrelated surfaces at once
  • the daemon mostly restates known information without changing decisions or state
  • the outputs land somewhere the team does not already monitor
  • the role depends on too much hidden human context
  • the daemon would create follow-up work faster than the team can absorb it
  • the role is so broad that almost every activation would need judgment outside clear boundaries

​
What Charlie needs in order to recommend daemons well

When asking Charlie to recommend daemons, provide:
  • the recurring maintenance problems you want daemons to own
  • the repo or team surfaces where that work appears today, such as GitHub, Linear, or Slack
  • the areas of the repo or workflow that matter most
  • any boundaries the daemon should respect
  • any especially noisy areas that should be avoided
If the team already has strong norms, include them. Daemon selection is much better when Charlie knows what “healthy” looks like for this team.

​
Native-surface fit

Choose outputs that match the system of record the daemon is maintaining. As a rule:
  • use GitHub-facing output for PR, repo, and codebase maintenance
  • use Linear-facing output for issue or project-graph hygiene
  • use Slack-facing output for escalation, summaries, low-blast-radius rollout, or cases where the right first step is visibility rather than mutation
A daemon should produce work where the team already expects to see and review that kind of work. If a daemon’s output would feel out of place on the target surface, re-scope the daemon or choose a different surface.

​
How to use the examples repo when choosing daemons

Start with the examples repo README: examples repo README Use the examples repo to:
  • find the nearest existing pattern
  • calibrate scope
  • see how similar daemon roles are bounded
  • compare different wake shapes and output postures
  • understand how narrow, explicit roles are actually written
Do not treat the examples as the full space of valid daemons. Use them as pattern anchors, not as a menu of all allowed roles. If no example exactly matches the repo’s problem, choose the nearest pattern and adapt the role to the repo’s actual maintenance gap. Where the current public examples are PR-heavy, take the role shape, scoping discipline, and output posture from them rather than copying the literal surface.

​
A simple selection rubric

A daemon idea is promising when the answer is “yes” to most of these:
  • Is this work recurring?
  • Is the role narrow enough to explain in one sentence?
  • Can the daemon wake from clear events, schedules, or both?
  • Can the team review the daemon’s outputs on native surfaces?
  • Would small, repeated activations be useful here?
  • Is this likely to create signal rather than noise?
  • Can the daemon be rolled out narrowly first?
A daemon idea is weak when the answer is “no” to most of these.

​
Recommendation clarity check for daemon recommendations

When Charlie recommends daemons, the recommendation should make these points explicit:
  • the daemon’s purpose
  • why this role is worth creating now
  • whether it should be watch-driven, schedule-driven, or hybrid
  • what makes the role narrow enough to start safely
  • where the daemon’s output should appear
  • which example daemon is the closest analog, if any
If Charlie cannot explain those clearly, the daemon idea is probably not ready.