This was an interesting experiment with AI agents building themselves, but ultimately a general purpose agent such as openclaw or hermes variants integrated with engineeering process is far more effective due to its extensive eco-system and integrations. The major learning is the ecosystem is changing so fast and general purpose agents may work for 80% rather than the 20%.
Autonomous GitHub repository management powered by Copilot and github app.
Documentation: https://ianlintner.github.io/caretaker/
One issue. No CLI. No tooling. Paste a setup issue into your repo, assign it to @copilot, walk away. Your repo is now autonomously maintained.
- You paste a setup issue into your repo and assign it to
@copilot - Copilot reads our SETUP_AGENT.md, analyzes your repo, and opens a PR with everything configured
- You merge the PR
- The orchestrator runs daily via GitHub Actions, managing PRs, issues, and upgrades
The orchestrator uses Copilot as its execution engine — it observes your repo state, decides what needs to happen, and delegates code changes to Copilot via structured comments.
Tip: Visit the Getting Started docs and use the copy button on the code block below to copy the issue template in one click.
## Setup Caretaker
@copilot Please set up the caretaker system for this repository.
### Instructions
1. Read the setup guide at:
https://github.com/ianlintner/caretaker/blob/main/setup-templates/SETUP_AGENT.md
2. Follow the instructions in that guide exactly.
3. After creating all files, open a single PR with the changes.
Title: "chore: setup caretaker"
### Context
This repo uses the caretaker system for automated repo management.
See: https://github.com/ianlintner/caretaker4. Add COPILOT_PAT from a write-capable user for Copilot hand-offs, and ANTHROPIC_API_KEY for enhanced AI features
COPILOT_PAT should be a fine-grained PAT that belongs to a real user or machine user with write access to the repository.
Caretaker uses that token for:
- API-based assignment of issues to GitHub Copilot
- PR comments that
@copilotmust see as coming from a write-capable identity rather thangithub-actions[bot]
After setup, your repo has:
.github/
copilot-instructions.md ← Copilot project memory (appended)
agents/
maintainer-pr.md ← PR agent persona
maintainer-issue.md ← Issue agent persona
maintainer-upgrade.md ← Upgrade agent persona
maintainer/
config.yml ← Repo-specific settings
.version ← Pinned version
No Python. No Node. No vendored code. No GitHub Actions workflow either — all execution happens server-side, driven by App webhooks. Just config and Copilot instructions.
When an agent needs to make a code change, it routes through the
ExecutorDispatcher, which picks one of four backends per dispatch:
- Copilot —
@copilothand-off comment (the legacy default). - Foundry — in-process LLM tool loop, drives Azure AI Foundry or
any LiteLLM-compatible provider directly from
mcp_backend. - HandoffAgent — tags the PR/issue and lets
claude-code-actionoropencode_localGitHub Actions run asynchronously. - K8s Job — durable per-task pod for long-running work; brokered
through Azure Service Bus and the
caretaker-job-dispatcherdeployment.
Three labels override per-item: agent:custom, agent:copilot,
agent:quarantine.
These eleven agents handle the day-to-day repository workload. Seven additional specialist agents (review, principal, refactor, perf, migration, test, bootstrap) are documented in docs/agents.md.
- Monitors all open PRs in real-time
- Detects and triages CI failures (test, lint, build, type errors)
- Requests fixes from Copilot via structured comments
- Retry loop with escalation after max attempts
- Auto-merge for Copilot, Dependabot, and human PRs (configurable)
- Handles flaky test detection and CI re-runs
- Review state analysis and auto-approval (configurable)
- Triages incoming issues (bug, feature, question, duplicate, stale)
- Dispatches implementable issues through the configured coding backend
- Tracks issue → PR → merge lifecycle
- Auto-closes answered questions and stale issues (configurable)
- Escalates complex issues to repo owners
- Monitors default-branch CI failures
- Automatically creates fix issues for build/test failures
- Deduplicates similar issues with cooldown periods
- Routes fixes through the configured coding backend
- Detects
mcp_backendand dispatcher failures - Creates self-diagnosis issues
- Reports bugs to upstream caretaker repository (configurable)
- Ensures the system can maintain itself
- Triages Dependabot alerts
- Monitors code scanning findings
- Tracks secret scanning alerts
- Filters by severity thresholds
- Creates remediation issues with context
- Reviews Dependabot PRs
- Auto-merges patch and minor updates (configurable)
- Posts dependency update digests
- Smart merge strategies by update type
- Reconciles merged PRs into changelog updates
- Maintains documentation freshness
- Configurable lookback period
- Optional README updates
- Cleans up duplicate caretaker-managed issues and PRs
- Closes abandoned work after 14-day default window
- Prevents operational clutter accumulation
- Exempt label support for critical work
- Warns and closes stale issues and PRs (60+ days default)
- Deletes merged branches automatically
- Configurable stale thresholds
- Exempt labels for pinned or security work
- Creates human escalation digest issues
- Aggregates work requiring maintainer attention
- Configurable targets and notification
- Tracks escalation age and priority
- Detects new caretaker releases
- Creates upgrade issues for the configured coding backend to execute
- Supports multiple strategies: auto-minor, auto-patch, latest, pinned
- Handles breaking vs. non-breaking upgrades
- Version pinning via
.versionfile - Preview channel support
- Quantitative goal-based agent dispatch
- Measures repository health across dimensions:
- CI health (green builds on main and PRs)
- PR lifecycle velocity
- Security posture
- Self-health monitoring
- Scores each goal from 0.0 (unmet) to 1.0 (satisfied)
- Prioritizes agents based on goal impact
- Detects divergence and critical states
- Tracks goal history for trend analysis
- Disk-backed SQLite storage for agent memory
- Persistent deduplication across runs
- Namespaced memory for different agent concerns
- Automatic snapshot generation for auditing
- Bounded storage with configurable limits
Add ANTHROPIC_API_KEY to unlock enhanced AI features:
- CI log analysis — better at parsing long, noisy logs
- Architectural review — understands complex code review comments
- Issue decomposition — breaks down multi-faceted bugs
- Upgrade impact analysis — assesses breaking change risk
Set OPENROUTER_API_KEY (or its accepted alias OPEN_ROUTER_API_KEY)
and provider: openrouter in
.github/maintainer/config.yml to route LLM calls through
OpenRouter, which gives you:
- 300+ models behind one key — DeepSeek R1, Gemini, Llama, Qwen, GLM, plus all the proprietary frontier models.
- Per-feature model routing — pin different caretaker features to
different best-fit models via
feature_models. - Web-grounded analysis — append
:onlineto a model string to add a web search step before the completion. Caretaker ships this as the default forupgrade_impact_analysis,migration_analysis, andmigration_planso release-note and breaking-change context comes from current sources rather than stale model knowledge.
Sample config:
llm:
provider: openrouter
default_model: openrouter/anthropic/claude-sonnet-4.6
feature_models:
ci_log_analysis:
model: openrouter/deepseek/deepseek-r1
principal_architecture_review:
model: openrouter/anthropic/claude-opus-4.6Cost note: :online adds OpenRouter's web-search step
(~$4 per 1k searches) on top of the model call. The
caretaker.llm.online=true OTel span attribute lets you break out
web-grounded spend in cost dashboards.
When provider: openrouter is set, every model string must begin
with openrouter/. Caretaker rejects bare model names at
config-load to prevent the silent bypass to Anthropic-direct that
LiteLLM otherwise performs.
Each consumer repo's successful caretaker run can POST a small
heartbeat to a central caretaker backend so an operator sees every
managed repository in one dashboard — without running an org-wide
GitHub crawl.
Enable in .github/maintainer/config.yml:
fleet_registry:
enabled: true
endpoint: https://<your-caretaker-backend>/api/fleet/heartbeatSee docs/fleet-registry.md for architecture, payload shape, and HMAC-signed delivery.
Small tasks (lint fixes, trivial test failures, review comments) no
longer have to go to copilot-swe-agent[bot]. A configurable
executor routes them to caretaker's own Foundry tool-loop or to an
anthropics/claude-code-action hand-off, with a size-budget guard
and an explicit escalation path back to Copilot.
Three routing labels let operators steer individual items:
agent:custom— force the custom executor.agent:copilot— force the legacy path.agent:quarantine— refuse dispatch (for hostile or confusing issues).
On AKS deployments, the MCP backend exposes
POST /api/admin/agent-tasks which spawns a short-lived
batch/v1 Job per dispatch. See
docs/custom-coding-agent-plan.md
for the full design, phased rollout, size budget, and security model;
docs/custom-coding-agent-e2e.md
for the operator runbook.
See setup-templates/templates/config-default.yml for the full config schema.
Key settings:
pr_agent:
auto_merge:
copilot_prs: true # Auto-merge Copilot PRs
dependabot_prs: true # Auto-merge dependency updates
copilot:
max_retries: 2 # Fix attempts before escalation
issue_agent:
auto_assign_bugs: true # Auto-assign simple bugs to Copilot
auto_assign_features: false
devops_agent:
target_branch: main # Monitor default branch CI
max_issues_per_run: 3 # Prevent issue spam
dedup_open_issues: true
security_agent:
min_severity: medium # Filter by severity
include_dependabot: true
include_code_scanning: true
include_secret_scanning: true
dependency_agent:
auto_merge_patch: true
auto_merge_minor: true
post_digest: true
charlie_agent:
stale_days: 14 # Short janitorial window for caretaker-managed work
close_duplicate_issues: true
close_duplicate_prs: true
stale_agent:
stale_days: 60 # General stale threshold
close_after: 14
delete_merged_branches: true
upgrade_agent:
strategy: auto-minor # auto-minor | auto-patch | latest | pinned
channel: stable # stable | preview
goal_engine:
enabled: false # Experimental: goal-driven dispatch
goal_driven_dispatch: false # Reorder agents by goal impact
divergence_threshold: 3 # Runs before triggering alerts
memory_store:
enabled: true # Persistent agent memory
db_path: .caretaker-memory.db
max_entries_per_namespace: 1000The orchestrator runs server-side on AKS, not in your repo. Three deployable processes split the work:
GitHub App webhooks
│
▼
mcp_backend (FastAPI x2, AKS)
│ ├── HMAC + allow-list
│ ├── dedup + rate-limit
│ └── Redis Streams ──► agent router ──► ExecutorDispatcher
│ │
│ ├──► Copilot @-mention (legacy)
│ ├──► Foundry (in-process LLM tool loop)
│ ├──► HandoffAgent (opencode_local / claude-code-action)
│ └──► Azure Service Bus ──► caretaker-job-dispatcher
│ │
│ ▼
│ per-task K8s Job
│ │
▼ ▼
MongoDB / Cosmos · Neo4j · SQLite git push + PR comment
Eighteen agents live behind the dispatcher, grouped by trigger (event-driven, scheduled, dispatch-time / advisory). The orchestrator never writes code itself — it routes to one of four coding backends.
For diagrams of the runtime topology, webhook event pipeline, durable coding-job lifecycle, and full agent inventory, see docs/architecture.md.
# Clone and install
git clone https://github.com/ianlintner/caretaker.git
cd caretaker
pip install -e ".[dev]"
# Run tests
pytest tests/ -v
# Lint
ruff check src/ tests/
ruff format --check src/ tests/
# Type check
mypy src/MIT