agent-minder

minder

A self-hosted orchestration layer for Claude Code. Automatically dispatch the right agent for the job, whether that's a scheduled cron task (dependency updates, security scans, doc syncs) or a reactive trigger from a GitHub label. Tag an issue with bug and a bug-fixer agent reproduces it, writes a regression test, and opens a PR. Runs in the foreground for inspection or as a background daemon.

Need to check in on a more complex job? Run minder checkout for follow-up options: view logs, restore the worktree for manual testing, resume with a fresh Claude session that has the agent's context preloaded, or jump straight to the PR.

Powers automated development on ripit.fit.

Why minder?

If you want to dispatch Claude Code interactively, claude agents is great. minder is for the headless half: work that should happen without you typing a prompt.

A few things that make it useful as a devops-minded layer:

• The unit of work is a GitHub issue. Tag one with bug or agent-ready from anywhere — your phone, an admin panel, a Slack action, a teammate's laptop — and the right agent picks it up. No local CLI required to dispatch.
• Configuration lives in .agent-minder/jobs.yaml, checked into the repo. You can grep it, diff it, code-review it, and version it alongside the agent definitions in .claude/agents/.
• Custom agents per task type: a spike posts research findings as a comment, autopilot opens a PR, bug-fixer writes a regression test before fixing the code. You tag once; the routing is done.
• Multi-stage pipelines with conditional routing. After an agent opens a PR, a reviewer agent grades it (low-risk, needs-testing, or suspect). Low-risk PRs can auto-merge once CI passes.
• minder enroll scans the repo, researches its stack and conventions, and generates tailored Claude Code agent definitions in .claude/agents/. The generated agents are standard subagents, usable inside or outside minder.
• Self-hosted and open source (MIT). Runs on your laptop in the foreground or as a daemon on a server with a remote client (minder status --remote host:port).

Quick start

# Install
go install github.com/aptx-health/agent-minder/cmd/minder@latest

# Authenticate (stores token in OS keychain)
minder auth login

# Or set env var
export GITHUB_TOKEN=ghp_...

# Enroll a repo (scans, installs agents, configures jobs)
minder enroll /path/to/repo

# Deploy on issues
minder deploy 42 --repo /path/to/repo --foreground

# For ongoing use: current dir, expose API, foreground visibility, generous budget
minder deploy --repo . --serve :7749 --foreground --max-turns 150 --budget 10 --total-budget 35

# Check status
minder status

--serve :7749 exposes the HTTP API so minder checkout and minder status can reach the daemon. The budget flags (--max-turns 150 --budget 10 --total-budget 35) leave headroom for complex jobs and work well if you're on Claude Max.

How it works

Issues -> Dependency graph -> Parallel agents -> Code review -> Lesson capture -> PR

Each agent runs in an isolated git worktree with its own branch. The supervisor manages concurrency, budget limits, and the review pipeline. Lessons from reviewer feedback get folded back into future agent prompts. Everything is tracked in SQLite at ~/.agent-minder/v2.db.

Features

Job scheduler

Define recurring jobs and label triggers in .agent-minder/jobs.yaml, similar to a CI/CD workflow file but for autonomous coding work. Reactive triggers (label-based) and scheduled jobs (cron) sit in one file, versioned with the repo:

jobs:
  weekly-deps:
    schedule: "0 9 * * 1"          # cron expression
    agent: dependency-updater
    description: "Check for outdated dependencies"
    budget: 3.0

  bug-triage:
    trigger: "label:bug"           # label trigger -> agent
    agent: bug-fixer

  spike:
    trigger: "label:spike"
    agent: spike
    description: "Research and discovery"
    budget: 5.0

The trigger map prints at startup so you can see exactly what's wired up:

minder jobs list                   # show schedules
minder jobs run weekly-deps        # manual trigger

Built-in agent types

Agent contracts

Agents declare their behavior in YAML frontmatter in .claude/agents/*.md:

---
name: dependency-updater
mode: proactive              # no issue needed
output: pr                   # opens a PR
stages:
  - name: scan
  - name: review
    agent: reviewer
    on_failure: skip
    retries: 1
context:                     # what context to inject
  - repo_info
  - file_list
  - recent_commits:7
  - lessons
dedup:                       # skip if duplicate work exists
  - branch_exists
  - open_pr_with_label:dependencies
  - recent_run:168
timeout: 1h
---

You are a dependency update agent...

Contract fields: mode (reactive/proactive), output (pr/issue/comment/none), context (providers), dedup (strategies), stages (multi-step pipeline), timeout.

Each agent type also declares meaningful pipeline stage names (e.g., autopilot's stage is implement, bug-fixer's is fix, spike's is research). Agents without explicit stages fall back to run.

Context providers

Agents get context assembled from declared providers:

Multi-agent orchestration

• Up to N concurrent agents (configurable with --max-agents)
• Slot backfill: as agents finish, new ones start automatically
• Budget ceiling with 80% warning and automatic pause

Automated review

After an agent opens a PR, a review agent assesses it:

• low-risk: clean, well-tested. Auto-merge eligible.
• needs-testing: looks correct but needs human verification.
• suspect: has issues requiring human review.

Review produces structured JSON with risk level, summary, lessons, and specific issues found. The extraction call has a 2-minute timeout to prevent hanging on concurrent reviews.

Learning system

Minder learns from agent outcomes:

• Lessons captured automatically from review findings
• Injected into future agent prompts (~2000 token budget)
• Tracks helpful/unhelpful counts per lesson
• Scoped per repo or globally
• Grooming auto-deactivates stale lessons; LLM consolidation merges overlapping ones

minder lesson list                        # show all lessons
minder lesson add "Always run tests"      # add manually
minder lesson groom --dry-run             # preview consolidation

Dedup engine

Stackable strategies prevent duplicate work:

• open_pr — skip if open PR exists for branch (default for reactive PR agents)
• branch_exists — skip if branch already exists on remote
• open_pr_with_label:<label> — skip if matching PR is open
• recent_run:<hours> — skip if same agent ran recently

Reactive PR agents automatically get open_pr dedup to prevent re-running issues across daemon restarts. Unlike branch_exists, this allows retries when the agent was interrupted (usage limit, crash) before opening a PR.

Watch mode

Continuously poll GitHub for new issues matching a filter:

minder deploy --watch label:agent-ready --serve :7749
minder deploy --watch milestone:v2.0

Trigger routes from jobs.yaml are polled automatically — --watch flag is optional when triggers are configured.

Daemon mode + HTTP API

Run as a background daemon with a REST API:

minder deploy 42 55 --serve :7749       # start daemon
curl localhost:7749/status | jq          # check status
curl localhost:7749/jobs | jq            # list jobs
minder stop <deploy-id>                  # stop daemon

Endpoints: /status, /jobs, /jobs/{id}, /jobs/{id}/log, /dep-graph, /metrics, /lessons, /stop, /resume.

Usage limit recovery

When an agent hits a Claude Code session/usage limit, minder automatically:

1. Detects the limit (via stream events or error text patterns)
2. Sets job status to waiting
3. Sleeps with backoff (1h, 2h, 3h)
4. Resumes the session using --resume <session_id>
5. Up to 3 retry attempts before bailing

No human intervention needed.

Command timeout wrappers

Test and build commands injected into agent context include timeout wrappers (default 5m for tests, 3m for builds). Configurable via test_timeout and build_timeout in onboarding.yaml. Prevents agents from burning turns waiting on hung processes.

Orphan process reaper

Agent runs occasionally leave detached descendants alive in the worktree — npm start, next dev, overmind and similar processes call setsid and escape their parent's process group, so they survive the agent that spawned them. The supervisor sweeps every worktree for these orphans and kills them (SIGTERM, then SIGKILL after a 2-second grace) at three points:

• after every agent process exits (scoped to that one worktree)
• at supervisor startup (across all worktrees whose jobs are not currently running)
• on a 5-minute ticker while the supervisor is running

Each kill emits one event line in foreground mode (e.g. [reaper] job#265 issue-699: killed pid=39076 ppid=1 cmd=next-server age=20m sig=KILL) and a structured component=reaper record in debug.log. Active agents' processes are never touched — the sweep skips any job in running state. For manual cleanup or testing: minder reaper sweep <worktree-path>.

SwiftBar menu bar plugin

A macOS menu bar widget that shows agent status at a glance. Supports all job statuses including waiting (usage limit recovery). See xbar/minder.5s.sh.

Commands

Deploy flags

Prerequisites

Environment variables

Development

Testing

go test ./...                              # all tests
go test ./internal/db/... -v               # DB + migrations
go test ./internal/supervisor/... -v       # supervisor, contracts, context, dedup
go test ./internal/scheduler/... -v        # cron parser, config, scheduler
go test ./internal/daemon/... -v           # HTTP API endpoints

Debug logging

MINDER_DEBUG=1 minder deploy 42 --foreground

# Watch in another terminal
tail -f ~/.agent-minder/debug.log | jq '{time, msg, agent, issue}'

Agent logs

Each agent run produces a stream-json log:

# List logs
ls ~/.agent-minder/agents/

# Watch a running agent
tail -f ~/.agent-minder/agents/<deploy-id>-issue-<N>.log | \
  jq -r 'if .type == "assistant" then (.message.content[]? |
    if .type == "tool_use" then "🔧 \(.name)" else empty end)
  else empty end'

Architecture

cmd/minder/main.go          # Entry point
cmd/                         # Cobra commands (deploy, status, stop, lesson, jobs, agents, auth, enroll, tui)
internal/
  supervisor/                # Job manager, context providers, contracts, dedup, review, bail, templates
  scheduler/                 # Cron parser, jobs.yaml, scheduled job firing
  daemon/                    # PID files, heartbeat, HTTP API server + client
  db/                        # SQLite schema (v4), models, queries, migrations
  claudecli/                 # Claude Code CLI wrapper
  github/                    # GitHub API client (go-github, ETag caching)
  git/                       # Git CLI wrappers
  auth/                      # OS keyring integration (macOS Keychain, Linux libsecret)
  lesson/                    # Lesson selection, injection, grooming
  onboarding/                # Repo scanning, onboarding YAML
  discovery/                 # Language/framework detection
  agentutil/                 # Agent log parsing
  sqliteutil/                # WAL recovery
xbar/                        # macOS SwiftBar menu bar plugin
.agent-minder/               # Per-repo config (jobs.yaml, onboarding.yaml)

Data storage

SQLite at ~/.agent-minder/v2.db (WAL mode, foreign keys, single-writer via SetMaxOpenConns(1)). Schema v4.