Skip to content
BranchesTags

Repository files navigation

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:

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

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 a configured package manager.
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.
GitHub issue hygiene github-bug-context-researcher daemons/github-bug-context-researcher/DAEMON.md Adds concise repository-aware triage context to newly opened GitHub bugs and regressions.
GitHub issue hygiene github-issue-duplicate-finder daemons/github-issue-duplicate-finder/DAEMON.md Suggests likely duplicate or related GitHub issues when new issues are opened.
GitHub issue hygiene github-issue-labeler daemons/github-issue-labeler/DAEMON.md Keeps recently changed GitHub issues aligned with the installed repository's current label set.
Linear issue hygiene linear-bug-context-researcher daemons/linear-bug-context-researcher/DAEMON.md Adds concise repo-aware triage context to newly created Linear bugs and regressions.
Linear issue hygiene linear-issue-duplicate-finder daemons/linear-issue-duplicate-finder/DAEMON.md Suggests likely duplicate or related Linear issues when new issues are created.
Linear issue hygiene linear-issue-labeler daemons/linear-issue-labeler/DAEMON.md Keeps recently changed Linear issues aligned with the current Linear label set.
Linear issue hygiene linear-pr-link-reconciler daemons/linear-pr-link-reconciler/DAEMON.md Finds likely GitHub code work for Linear issues and asks for confirmation without editing links automatically.
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 pr-review daemons/pr-review/DAEMON.md Reviews pull requests for concise, evidence-backed correctness and repository-policy risks before merge.
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.
Slack operations slack-alert-context-researcher daemons/slack-alert-context-researcher/DAEMON.md Replies to alert-like Slack bot messages with compact GitHub and incident context for triage.
Slack planning slack-meeting-followup-planner daemons/slack-meeting-followup-planner/DAEMON.md Turns Slack meeting notes or transcripts into concise, repo-aware follow-up options Charlie can help execute.

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/**.

Node examples API

Node consumers can import the packaged catalog API without shelling out to the CLI:

import {
  createDaemonInstallPullRequest,
  getDaemonExample,
  listDaemonExamples,
  listDaemonInstallPullRequests,
  loadDaemonExamplesCatalog,
} from "@charlie-labs/daemons";

const catalog = await loadDaemonExamplesCatalog();
const examples = await listDaemonExamples();
const example = await getDaemonExample("js-ts-dependency-upgrades");

await createDaemonInstallPullRequest({
  repo: "owner/repo",
  exampleId: "js-ts-dependency-upgrades",
  base: "main",
  adaptations: { package_manager: "pnpm" },
});

await listDaemonInstallPullRequests({ repo: "owner/repo" });

The catalog APIs read the package-root examples.json, so they work from the built npm package. The install-PR APIs render from the same catalog contract and use GitHub authentication through an explicit token/client or GITHUB_TOKEN / GH_TOKEN.

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 --adapt package_manager=pnpm

daemon pr open js-ts-dependency-upgrades --repo owner/repo --base main --adapt package_manager=pnpm

daemon pr list --repo owner/repo

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;
  • install plans include destination paths and file modes (100644/100755);
  • existing destination directories/files require --force;
  • deprecated examples require --allow-deprecated;
  • show surfaces structured adaptations[] and optional specializationIdeas[], and add/install/PR-open render {{adapt.key}} tokens with string-only values before validation;
  • daemon pr open writes an atomic GitHub commit on a deterministic charlie/daemon-installs/<example-id> branch, opens an install PR, and records only adaptation keys (not raw values) in the hidden PR marker and CLI output;
  • 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:

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

How Charlie should use these examples

When choosing daemons:

When creating or editing daemon files:

About

Charlie Labs catalog of suggested daemon files and agent skills.

Resources

Readme
Activity
Custom properties

Stars

30 stars

Watchers

0 watching

Forks

2 forks
Report repository

Contributors

Languages