@gethmy/agent

Push-based agent daemon for Harmony. Watches board assignments via Supabase Realtime and autonomously implements and reviews cards using Claude CLI workers in isolated git worktrees.

Built for failsafe auto mode: crashed daemons recover on restart, misconfigured columns fail fast, runaway costs trip a daily budget, and cards that can't pass build land in a dead-letter queue instead of bouncing forever.

Prerequisites

• Node.js >= 20 or Bun >= 1.0
• Claude Code CLI installed
• Git
• A Harmony account with an API key
• @gethmy/mcp configured (npx @gethmy/mcp setup)

Installation

# Run directly (works with any package manager)
npx @gethmy/agent@latest

# Or install globally
npm install -g @gethmy/agent
harmony-agent

Always pin @latest. A bare npx @gethmy/agent reuses any previously cached version that satisfies the spec — so an old install in ~/.npm/_npx can shadow the current release and you'll get stale startup logs and CLI behavior. npx @gethmy/agent@latest re-resolves to the newest published version. If you ever suspect a stale run, clear the cache with rm -rf ~/.npm/_npx (or install globally to skip npx caching entirely).

Configuration

1. Set up the MCP server first:

npx @gethmy/mcp setup

2. Add agent config to ~/.harmony-mcp/config.json. Every field is optional — the snippet below shows the common options with their defaults. For the full schema (worktree, verification, completion, priority labels), see docs/agent-daemon.md:

{
  "agent": {
    "poolSize": 3,
    "pickupColumns": ["To Do"],
    "claude": { "model": "opus", "escalateModel": "claude-fable-5", "reviewModel": "sonnet" },
    "review": {
      "enabled": true,
      "poolSize": 2,
      "pickupColumns": ["Review"],
      "moveToColumn": "Done",
      "failColumn": "To Do"
    },
    "budget": {
      "maxAttemptsPerCard": 3,      // DLQ after N full failed runs
      "maxCentsPerCard": 500,        // $5.00 per-card cost cap
      "dailyBudgetCents": 5000,      // $50.00 total daily cap
      "dlqLabel": "dlq"
    },
    "http": {
      "enabled": true,
      "port": 47821,
      "bindAddr": "127.0.0.1"
    },
    "timing": {
      "heartbeatMs": 30000,
      "staleHeartbeatMs": 120000,
      "reconcileIntervalMs": 60000,
      "worktreeGcIntervalMs": 300000
    }
  }
}

CLI

harmony-agent [run]              # Start the daemon (default)
harmony-agent status             # Snapshot: workers, queues, DLQ, budget
harmony-agent health             # Exit 0 if healthy, 1 otherwise
harmony-agent doctor             # Preflight checks without starting the daemon
harmony-agent gc                 # One-shot worktree garbage collection
harmony-agent dlq list           # List dead-lettered cards
harmony-agent dlq clear <cardId> # Release a card from the DLQ
harmony-agent help               # Show usage

# Flags:
--pretty                         # Force colored human log output
--json                           # Force JSON (one record per line)
                                 # Default: pretty on a TTY, JSON when piped

status, health, and dlq clear route through the running daemon's HTTP server (127.0.0.1:47821 by default). dlq clear falls back to a direct state-store write only when the daemon is offline.

What the daemon does

1. Watches the board in real time via Supabase Realtime.
2. Picks up cards assigned to your agent user from configured columns.
3. Implements changes in an isolated git worktree using a full-tool Claude run.
4. Verifies the build + lint pass. Failures trigger an auto-fix attempt. Persistent failures move the card back to the verification.failColumn (default: To Do).
5. Pushes the branch and moves the card to Review.
6. Reviews the diff with a read-only Claude run against a live dev server. Verdict is either approved (PR created, Ready to Merge label) or rejected (findings posted, card moved back to pickup).

Guarantees

• Resumable. A crash never orphans a card. On restart the daemon reconciles its own ghosts, returns implement cards to the pickup column with an agent-recovered label, ends their Harmony sessions, and cleans up worktrees.
• Trustworthy. The review worker refuses to approve if the dev server didn't respond to an HTTP probe. Infrastructure failures are distinguished from code failures, so valid PRs don't get bounced back to rework.
• Bounded. Per-card attempt and cost caps plus a daily budget cap prevent runaway spend. When caps hit, cards go to a dead-letter queue with a label instead of silently re-queuing.
• Observable. Structured JSON logs on stderr (pipe to jq), a local HTTP status endpoint, and per-worker heartbeats so the reconciler can detect zombie runs within 2 minutes.
• Safe. Claude subprocesses run in their own process group. Cancellation (SIGINT → SIGTERM → SIGKILL) terminates the whole subprocess tree, including build tools and dev servers Claude spawned.

State

Durable state lives at ~/.harmony-mcp/agent-state.json. Tracks live runs, per-card attempts and costs, daily spend, and DLQ markers. Atomic writes via write-to-tmp + rename.

Worktrees live at .harmony-worktrees/ inside your repo. A background sweep every 5 minutes removes directories older than 1 hour that no live run claims.

Debugging

Every Claude CLI run writes a per-run log at ~/.harmony-mcp/runs/<runId>-card-<shortId>.log — full stdout (NDJSON), stderr, parse errors, and an exit footer with tool-call and cost totals. Start there when a run ends silently or the card activity log shows only "Still working..." heartbeats.

See Debugging a Silent Run for interpretation table and retention notes.

See docs/agent-daemon.md for the full architecture.