Daemons Specification

This is the technical specification for the daemon file format. If you're new to daemons, start with the overview.

Where an agent executes a task with a start, an end, and a definition of done, a daemon fills a role with ongoing responsibilities and no finish line. The daemon file is a role description: purpose defines the mission, routines are standing responsibilities, deny is the authority boundary. Define a role once, not a task every time.

Daemon file

A daemon is a directory containing a DAEMON.md file

.agents/daemons/<daemon-id>/
  DAEMON.md          # Required
  scripts/           # Optional: executable helpers the daemon can call
  references/        # Optional: policy docs, templates, style guides the daemon can read

The DAEMON.md file contains YAML frontmatter followed by markdown content. The frontmatter is declarative. It defines what the daemon is and what it's allowed to do. The content below it is operational guidance the model interprets at runtime.

Frontmatter

Validation

• id, purpose, and routines are required.
• At least one of watch or schedule must be present. Both can be present.
• If schedule is present, it must be a valid five-field cron expression.

watch:
  - when a pull request is opened
  - when a maintainer comments "/daemon help" in a PR
  - when files matching docs/**/*.md are changed

# Bad: not observable, not an event, too broad
watch:
  - when code quality is low
  - when the repo needs attention
  - when code changes

routines:
  - propose clearer PR titles and summaries
  - identify missing test evidence in PR descriptions
  - suggest focused follow-up tasks when context is incomplete

deny:
  - merge pull requests
  - approve pull requests on behalf of humans
  - push commits directly to protected branches
  - delete files or directories

0 9 * * *          # daily at 09:00
0 */6 * * *        # every 6 hours
30 14 * * 1-5      # weekdays at 14:30

Content

The markdown body below the frontmatter is where you define how the daemon operates. There are no format restrictions. Write whatever helps the model execute the daemon's role effectively. Commonly useful sections:

Activation model

A daemon can activate in three patterns:

• Watch-only — wakes when a watch condition matches an event.
• Schedule-only — wakes when the cron schedule fires.
• Hybrid — both watch and schedule are present. Either can wake the daemon independently.

Each wake-execute cycle is one activation. The daemon wakes, receives context about why it woke, executes its routines within its deny rules and content guidance, and completes.

Examples

Complete daemon files

PR Helper (watch-only)

A daemon that reduces time to merge by fixing merge-blocking issues before they require a human round-trip.

Librarian (hybrid)

A daemon that keeps repository documentation current by detecting stale docs on every merge and sweeping for gaps on a daily schedule.

Bug Triage (watch-only)

A daemon that ensures every bug issue is complete, prioritized, assigned, and root-cause-analyzed.

Provider Guide

Building daemon support into a runtime

This section is for teams building daemon support into a cloud-based AI agent runtime. It explains how to interpret the daemon file format and what infrastructure is needed to run daemons.

Daemons extend the Agent Skills model into persistent, background processes. Where skills activate on demand during a conversation, daemons activate on events and schedules with no human in the loop. The daemon author drops a markdown file in their repo. The provider's job is to make the rest seamless: discovery, activation, and execution, without the team monitoring uptime or restarting processes.

File discovery

Scan repositories for DAEMON.md files at .agents/daemons/*/DAEMON.md. Each subdirectory under .agents/daemons/ represents one daemon. If a scripts/ or references/ directory exists alongside the daemon file, it is part of that daemon's support tree and should be accessible to the model during execution.

A repository can contain multiple daemons. Each operates independently.

Parsing and validation

Extract the YAML frontmatter from the markdown body. Validate that required fields (id, purpose, routines) are present and that at least one of watch or schedule is defined. If schedule is present, validate that it is a parseable five-field cron expression.

How you handle invalid daemon files is up to you. Options include rejecting the file at registration time, warning the team, or skipping the daemon silently. Surfacing errors to the team is recommended so authors can fix problems.

Watch condition mapping

Watch conditions are natural-language strings that describe events. Your runtime is responsible for interpreting them and mapping them to concrete event sources: webhooks, event subscriptions, polling, or whatever mechanism your platform supports.

The spec does not define a canonical set of event types. Authors write conditions like "when a pull request is opened" or "when files matching docs/**/*.md are changed" and the provider interprets them. This keeps daemon files portable across providers while allowing each provider to support events through whatever infrastructure they have.

Common phrasings include:

when a pull request is opened
when a pull request is updated / synchronized
when a pull request is merged
when a PR comment is created
when an issue is created / updated / labeled
when files matching <pattern> are changed
when a Sentry alert fires
when a commit is pushed to <branch>

These examples are illustrative, not normative. When a watch condition doesn't map to any event source your platform supports, the handling is at your discretion.

Schedule evaluation

If a schedule field is present, evaluate it as a standard five-field cron expression (minute, hour, day-of-month, month, day-of-week). Wake the daemon when the cron expression fires.

Timezone handling, missed-schedule behavior, and jitter are implementation details left to the provider.

Activation

An activation is a single wake-execute cycle. The daemon wakes, receives context, executes, and completes.

When both watch and schedule are present, either can wake the daemon independently. A schedule firing does not suppress pending watch activations, and vice versa.

At activation time, the model should receive enough context to execute effectively. A good activation context includes:

• The full daemon file (frontmatter and content).
• The event payload or schedule tick that triggered the activation.
• Access to the daemon's support tree (scripts/, references/).
• State from prior activations if your runtime supports persistent memory.

The richer the context, the better the model can follow instructions like limits ("no more than 3 PRs per day") and coordination ("don't comment on PRs with an active human review").

Content interpretation

Everything in the daemon file body, plus routines and deny from the frontmatter, is natural language interpreted by the model at runtime. The quality of interpretation is the provider's differentiator.

The contract

Pass the full daemon file to the model faithfully. Do not truncate, rewrite, or selectively omit sections. The model receives the complete frontmatter and content as authored by the customer.

If the content exceeds your model's context window, the handling is at your discretion, but the default should be to include the full file. Daemon files that are too large for the context window are an authoring problem, not a runtime problem.

What the model interprets

All of the following are model-interpreted, not mechanically enforced:

The distinction matters: your runtime mechanically handles file discovery, event mapping, cron evaluation, and activation. Everything else is the model's job.

Support tree access

Make the support tree available to the model during execution. Scripts should be executable. Reference files should be readable as context. The model decides when and how to use them based on the content instructions.

Platform requirements

Execution environment

Daemons need a compute environment with network access to the team's integrated systems: GitHub, Linear, Slack, Sentry, and other systems of record. Credential management and permission scoping are important. Isolating daemon execution so one daemon cannot interfere with another is recommended.

Supported Platforms

These are the required capabilities for a platform to support daemons.

Output delivery

Daemons produce work in native surfaces: PR comments and commits in GitHub, issue updates in Linear, messages in Slack. Your runtime needs integrations with the systems the daemon writes to.

Daemon output should be attributable. Teams need to distinguish daemon-produced work from human work. How you implement attribution (bot accounts, labels, metadata) is up to you.

Idempotency matters. If an activation is retried, the daemon should not duplicate its output.

State persistence

Daemons benefit from state that persists across activations. Activation history, accumulated context, and counter state all help the model follow instructions more accurately over time.

A daemon with no persistent state can still function, but it will be unable to follow instructions that reference prior activations and will not improve through accumulated context.

Lifecycle management

When a daemon file is added, modified, or removed from a repository, your runtime needs to respond. Common approaches include watching for commits that touch .agents/daemons/ and updating registrations accordingly.

Portability

Daemon files are intended to be portable across providers. A daemon file authored for one runtime should work on another without modification.

Portability depends on providers converging on similar interpretations of natural-language watch conditions. The spec intentionally leaves interpretation to the provider, but common phrasings like "when a pull request is opened" should be interpreted consistently across providers.

If your runtime supports event types that other providers may not, document them so daemon authors can make informed decisions about portability.