convez.ai
AgenteAutomaçãoIntermediário
aptx-health

Agent Minder

aptx-health/agent-minder

Orquestrador headless para Claude Code com cron e GitHub labels

Ver no GitHub
InicialPluginScore · de 0 a 100

Camada de orquestração self-hosted para Claude Code que automatiza tarefas baseadas em agendamento (cron) ou triggers de GitHub (labels). Dispara agentes específicos para diferentes tipos de trabalho — correção de bugs, atualizações de dependências, varreduras de segurança — sem intervenção manual, com suporte a pipelines multi-stage e roteamento condicional.

Instalação

$npx convez-ai aptx-health/agent-minder

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
1
Acompanhando
0
Saúde
75%
Último commit
há 2 meses
Versão
v0.3.2
Issues abertas
35
Contribuidores
2

Casos de uso

  • Automatizar correção de bugs com agentes especializados disparados por labels
  • Agendar tarefas repetitivas (atualizações de dependências, scans de segurança, sínc de docs)
  • Implementar pipelines CI/CD com roteamento condicional entre agentes
  • Revisar e mesclar PRs automaticamente com agentes de code review

Veredito

Solução madura e bem-pensada para quem quer automação verdadeira com Claude Code, não apenas prompts ad-hoc. Exige Go e configuração de repositório, mas oferece controle fino sobre pipelines com agents — ideal para equipes e infraestrutura.

README

A tradução para o português deste README ainda está na fila.

minder

CI License: MIT Go Version

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.

minder checkout — follow-up options for any agent's work

Powers automated development on ripit.fit.

minder checkout — months of agent work across one repo

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 deploy — trigger map and live dispatch on startup

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

Built-in agent types

AgentModeOutputDefault triggerDescription
autopilotreactiveprlabel:agent-readyImplements GitHub issues end-to-end
reviewerreactivepr(auto)Reviews PRs, assesses risk, makes fixes
bug-fixerreactiveprlabel:bugReproduces bugs, writes regression tests, fixes
spikereactiveissuelabel:spikeResearch and discovery; investigates questions and posts findings
dependency-updaterproactiveprcronScans and updates outdated dependencies
security-scannerproactiveissuecronRuns security audits, reports findings
doc-updaterproactiveprcronSyncs documentation with code changes

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:

ProviderDescription
issueIssue title, body, and comments from GitHub
repo_infoLanguages, test/build commands with timeout wrappers, base branch, worktree path
file_listRepository file tree (depth 3)
recent_commits:<days>Git log from last N days
lessonsRelevant lessons from the learning system
sibling_jobsOther jobs in the same deployment
dep_graphDependency graph for the deployment

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

CommandDescription
minder deploy [issues...] [flags]Launch agents on issues or start daemon
minder status [deploy-id]Show deployment status (--json for structured output)
minder stop [deploy-id]Stop a running deployment
minder tuiLaunch interactive TUI dashboard
minder auth login|status|logoutManage GitHub token in OS keychain
minder lesson add|list|edit|remove|pin|groomManage the learning system
minder jobs list|runView and trigger scheduled jobs
minder agents list|show|addList, inspect, or create agent definitions
minder checkout [issue]Check out an agent's worktree for review (interactive picker, --remote)
minder logs [issue]View agent log output (interactive picker, --follow, --remote, --raw)
minder enroll [repo-dir]Scan a repo and generate onboarding config

Deploy flags

FlagDefaultDescription
--repo <dir>.Repository directory
--agent <name>autopilotAgent type to use
--watch <filter>—Watch for issues (label:<name> or milestone:<name>)
--serve <addr>—Start HTTP API (e.g., :7749)
--foreground—Don't daemonize
--max-agents <n>3Concurrent agent slots
--max-turns <n>50Per-job turn limit
--budget <usd>5.00Per-job budget
--total-budget <usd>25.00Total deployment budget
--auto-merge—Auto-merge low-risk PRs (waits for CI)
--base-branch <name>auto-detectBase branch for worktrees/PRs
--api-key <key>—Require API key for HTTP access

Prerequisites

DependencyPurpose
Go 1.25+Build from source
gitWorktree management, branch operations
Claude Code CLIAgent execution (claude --agent)
GITHUB_TOKENGitHub API access (via env var or minder auth login)
gh CLIAgents use gh for PR creation and issue management

Environment variables

VariableDefaultDescription
GITHUB_TOKEN—GitHub API token (or use minder auth login)
MINDER_DB~/.agent-minder/v2.dbDatabase path
MINDER_LOG~/.agent-minder/debug.logDebug log path
MINDER_DEBUG—Enable structured JSON debug logging
MINDER_API_KEY—API key for remote daemon access

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.

TablePurpose
deploymentsDeploy runs with config (agents, budget, model, base branch)
jobsWork queue (agent, status, worktree, PR, cost, stages, results)
job_schedulesCron schedules with last/next run tracking
dep_graphsLLM-generated dependency graphs
lessonsPersistent feedback with effectiveness tracking
job_lessonsWhich lessons were injected into which jobs
repo_onboardingCached repo scanning results
Ver o original no GitHub

Bom para

Relacionados