Charlie Labs and the daemon as a role, not a task

The anatomy of a daemon

A DAEMON.md file has two parts. The frontmatter is the durable contract: five fields that define what the daemon is, when it wakes, what it does, and what it must never do. The markdown body is operating guidance: decision policies, communication rules, verification requirements, limits, and examples.

The frontmatter fields:

id is the daemon's canonical identifier. It must match the directory name exactly. Once published, it's treated as permanent, never renamed for cosmetic reasons.

purpose is a single sentence describing the outcome the daemon exists to achieve. The docs are specific about this: write the outcome, not the mechanics. "Keeps repository docs current" not "Scans for stale markdown files." The purpose frames the daemon as a role, not a script.

watch is a list of observable events that trigger activation. "A GitHub pull request review is submitted on an open non-draft pull request." "A Linear issue is created for a bug or likely regression." Watch conditions must describe concrete events, not derived states. "When code quality is low" isn't a valid watch condition because there's no specific moment to wake on.

routines are the concrete operations the daemon performs. Each routine must be finite and verifiable: something a human could confirm happened or didn't. "Push a focused evidence-grounded fix to the PR branch when the correct repo change is clear." Not "Improve code quality."

deny lists the hard prohibitions. This is where the design gets interesting. The deny rules aren't generic safety slogans. They're specific to the daemon's scope and address the adjacent risks, the shortcuts the daemon might naturally attempt to reach its goals faster. A PR check repair daemon is denied from refreshing branches, merging PRs, or pushing speculative changes. A bug triage daemon is denied from changing issue fields, labels, or assignees. Every boundary is named explicitly rather than left to the runtime's judgment.

schedule is an optional five-field cron expression for time-based activation. A dependency update daemon runs 0 8 * * 1 (Monday mornings). A docs staleness scanner runs weekly. Daemons can be watch-only, schedule-only, or hybrid.

The catalog

Charlie Labs publishes fourteen example daemons in their open catalog. Each one is a complete DAEMON.md with paired metadata, and some include helper scripts. The catalog spans five categories of maintenance work.

PR lifecycle. Four daemons cover the pull request surface: pr-check-repair diagnoses and fixes failing CI checks, pr-merge-conflict-repair resolves merge conflicts on non-draft PRs, pr-metadata keeps PR titles and descriptions current, and pr-review-triage processes review threads to identify which feedback is valid, which is fixed, and which is duplicate. The review triage daemon is the most complex in the catalog, with detailed disposition logic (valid, invalid, duplicate, fixed, uncertain) and separate action policies for human-authored versus non-human feedback.

Linear issue hygiene. Four daemons work the Linear surface: linear-issue-labeler keeps labels aligned with the current label set, linear-bug-context-researcher adds repo-aware triage context to new bugs, linear-issue-duplicate-finder suggests likely duplicates when new issues arrive, and linear-pr-link-reconciler finds likely GitHub code work for Linear issues and asks for confirmation before linking.

Documentation freshness. Two daemons handle docs: docs-drift-maintainer repairs drift caused by recent merged source changes, and docs-stale-maintainer runs weekly sweeps for older outdated documentation. Both have hard limits on commit volume per activation.

Dependency maintenance. The js-ts-dependency-upgrades daemon scans for available patch and minor updates, groups them by runtime versus dev dependencies, and opens at most two PRs per run. It respects the repo's configured package manager and won't attempt major-version upgrades unless explicitly allowed.

Operations. Two daemons work Slack: slack-alert-context-researcher replies to alert-like bot messages with compact GitHub and incident context, and slack-meeting-followup-planner turns meeting notes into repo-aware follow-up options. A github-activity-digest daemon posts periodic summaries of meaningful PR and CI activity.

The catalog is installable via a CLI: daemon add js-ts-dependency-upgrades --adapt package_manager=pnpm scaffolds the daemon into your repo with the adaptation applied. The --dry-run flag previews what would be written. A daemon pr open command creates a GitHub PR that adds the daemon files, so the installation itself goes through code review.

Bounded autonomy as a design principle

The most consistent theme across the daemon catalog is restraint. Every daemon in the catalog is scoped to a narrow maintenance role, given explicit limits on output volume, and denied the shortcuts that would make it faster but less trustworthy.

The pr-check-repair daemon illustrates the pattern. Its purpose is to fix failing CI checks on non-draft PRs. It can push fixes, rerun flaky checks, or comment with a blocking reason. But it cannot refresh branches from base, cannot merge PRs, cannot approve or request changes, cannot force-push, and cannot make product or security decisions just to make checks pass. It must re-fetch the remote PR head before editing and again before pushing, to avoid overwriting concurrent human work.

The linear-bug-context-researcher daemon is even more constrained. It adds triage context to new bugs. It can post one comment. It cannot change issue fields, labels, state, assignee, priority, project, cycle, estimate, or description. It cannot create, edit, close, merge, label, assign, or comment on GitHub issues or pull requests. The daemon's scope is: read the bug, research context, post one useful comment, stop.

This level of constraint isn't accidental. The authoring guide explicitly frames it as a design principle: "Write the narrowest daemon that can do the job." Start with 50 to 100 lines, 2 to 3 routines, and iterate after real activations show what the daemon actually needs. The guide warns against unbounded routines ("help with code"), vague watch conditions ("when the repo needs attention"), and missing deny rules for risky actions.

Trust builds from the deny rules outward. A daemon that can push commits but not merge them, that can comment but not approve, that can research but not edit issue fields, earns trust incrementally. Each denied action is a boundary the team doesn't have to police manually. If the daemon's scope needs to expand later, the expansion shows up as a diff to the DAEMON.md file, visible in code review, not as a surprise behavior change.

The role model versus the task model

The deeper question the daemon format raises is whether "role" is a better abstraction than "task" for recurring background work.

Most agent orchestration tools model work as tasks: a trigger fires, a workflow runs, a result is produced. Loopy compiles workflows from triggers through typed events to sandboxed execution. Open-Inspect creates sessions per invocation. Claude Code Routines run prompts on a schedule. Each activation is a discrete unit with a beginning and end.

Charlie's daemon model adds a layer above individual activations. The daemon is a persistent role that spans many activations over time. The pr-check-repair daemon doesn't run once. It runs every time a check fails on every non-draft PR, accumulating context about the repo's CI patterns, common failure modes, and flaky tests. The docs-drift-maintainer doesn't scan once. It watches every merge for documentation impact and sweeps weekly for staleness. The daemon's identity persists across activations.

This has practical implications. A task-based system needs to inject all relevant context into each invocation. A role-based system can accumulate context across invocations, learning which CI failures are typically flaky, which docs are most prone to drift, which types of bugs get duplicate reports. The authoring docs mention "dedicated daemon memory" as coming soon, but even without it, the activation log provides continuity.

The tradeoff is configuration surface. A DAEMON.md file is more complex than a cron expression plus a prompt. The frontmatter alone has five fields, and the body can run to hundreds of lines of operating guidance. The pr-review-triage daemon in the catalog is detailed enough to be a mini operating manual. Teams will need to decide whether the upfront investment in writing and maintaining these files pays off through more predictable daemon behavior over time.