@charlie-labs/daemons

This repo contains example daemon files for common daemon patterns.

These examples are reference patterns for Charlie daemons. They are not the normative source of truth for the daemon format or for authoring rules.

Start here

Start with the docs:

• Daemons
• Choosing daemons
• Writing and editing DAEMON.md
• DAEMON.md reference
• Testing and iterating on daemons

For this repo's examples package, CLI, and catalog contract, use:

• Daemon catalog CLI
• Examples v2 package and catalog spec
• Examples authoring guide
• Examples catalog consumer guide

Read Daemons first if you are new to the concept.

Use DAEMON.md reference for the exact authored contract and Testing and iterating on daemons for testing and rollout guidance.

Example index

Category	Daemon ID	Path	Description
Dependency maintenance	js-ts-dependency-upgrades	daemons/js-ts-dependency-upgrades/DAEMON.md	Opens low-noise JavaScript/TypeScript dependency upgrade PRs with configured package-manager commands.
Documentation freshness	docs-drift-maintainer	daemons/docs-drift-maintainer/DAEMON.md	Repairs docs drift from recent merged source changes with small source-backed PRs.
Documentation freshness	docs-stale-maintainer	daemons/docs-stale-maintainer/DAEMON.md	Runs weekly to repair older outdated documentation in small source-backed PRs with a hard size limit.
GitHub activity reporting	github-activity-digest	daemons/github-activity-digest/DAEMON.md	Posts a low-noise scheduled digest of meaningful pull request and CI activity.
Linear issue hygiene	linear-issue-labeler	daemons/linear-issue-labeler/DAEMON.md	Keeps recently changed Linear issues aligned with a documented label taxonomy.
PR check repair	pr-check-repair	daemons/pr-check-repair/DAEMON.md	Repairs failing GitHub-visible PR checks with focused evidence-grounded commits, flaky reruns, or low-noise blocked comments.
PR merge conflict repair	pr-merge-conflict-repair	daemons/pr-merge-conflict-repair/DAEMON.md	Repairs clear merge conflicts on non-draft GitHub pull requests after target base branch changes, with focused verification and low-noise blocked comments.
PR metadata management	pr-metadata	daemons/pr-metadata/DAEMON.md	Keeps PR title/body metadata complete, current, and linked to the correct issue item.
PR review triage	pr-review-triage	daemons/pr-review-triage/DAEMON.md	Triages PR review threads and top-level PR comments for merge-readiness, duplicate feedback, fixed items, and safe low-noise follow-up.

Generated examples catalog

The root examples.json file is generated from each daemons/<id>/example.yml, DAEMON.md, and supported files under scripts/** and references/**.

Daemon catalog CLI

This package is npm-ready as @charlie-labs/daemons and exposes the daemon binary.

Use it to browse the public examples catalog, safely scaffold catalog examples into .agents/daemons/<id>/, and validate runtime daemon files:

daemon list

daemon show js-ts-dependency-upgrades --json

daemon add js-ts-dependency-upgrades --dry-run

daemon validate .agents/daemons/js-ts-dependency-upgrades/DAEMON.md

daemon validate --all --json

Key safety defaults:

• catalog reads default to master and support --ref <sha|branch|tag>;
• install copies only catalog-listed DAEMON.md, scripts[], and references[] files from the same ref;
• install never copies example.yml or crawls upstream directories;
• existing destination directories/files require --force;
• deprecated examples require --allow-deprecated;
• add/install/show always surface adaptationsRequired[] in JSON;
• scaffolding does not activate a daemon until the change is merged and ingested by Charlie.

See Daemon catalog CLI for command details, JSON envelope, validation semantics, and exit codes.

For release instructions, see Releasing @charlie-labs/daemons.

Use Examples v2 package and catalog spec for the exact package, metadata, generation, validation, and public-safety contract. Use Examples authoring guide for author/reviewer guidance. Use Examples catalog consumer guide for website, dashboard, and install consumer guidance.

Use the repo-owned checks before changing examples:

bun install
bun run generate:examples
bun run validate:examples
bun run test

examples.json is deterministic and should be committed whenever example packages change.

How to use this repo

Use this repo to:

• find the nearest example pattern
• calibrate scope and level of specificity
• compare watch-driven, schedule-driven, and hybrid shapes
• adapt a proven structure to your repo’s real maintenance role

Do not assume an example can be copied directly into your repo without changes.

The docs are the source of truth for:

• what daemons are
• what fields exist
• what the validation rules are
• what good daemon files look like
• how to test and iterate safely

Use the docs for concept, contract, and authoring guidance. Use this repo for concrete patterns.

How Charlie should use these examples

When choosing daemons:

• use Choosing daemons and the Example index to find the nearest pattern.

When creating or editing daemon files:

• use Writing and editing DAEMON.md and DAEMON.md reference, and treat examples as reference patterns rather than source of truth.
• use Examples authoring guide when adding or reviewing example packages in this repo.