kc-pr-daemon

All text output follows unified language preference. See plugin CLAUDE.md for query flow.

Overview

Manage the PR Review Closed-Loop Daemon — an external shell loop that automatically reviews and fixes PRs using claude -p.

Config: ~/.claude/kc-plugins-config/pr-flow/daemon.yaml Script: ${CLAUDE_PLUGIN_ROOT}/scripts/pr-review-daemon.sh Usage log: ~/.claude/audit/pr-daemon-usage.jsonl

Default (no subcommand)

When invoked without a subcommand (/kc-pr-daemon, pr daemon, daemon), show overview + status + next step:

PR Review Daemon
────────────────
Commands:
  /kc-pr-daemon start   — start daemon (mprocs or direct)
  /kc-pr-daemon stop    — stop daemon
  /kc-pr-daemon status  — usage stats (cost, iterations, last action)
  /kc-pr-daemon config  — view/edit settings

{status block — run the `status` bash snippet below}

Suggested next step:
  {if no usage log} → /kc-pr-daemon config — set up config first
  {if last run > 24h ago} → /kc-pr-daemon start — daemon not running
  {if last action was STUCK} → Check PR #{N} — daemon flagged it as stuck
  {if running normally} → /kc-pr-daemon status — view detailed stats

Commands

start

Option A — via project wrapper (recommended for teams):

Projects can ship a thin wrapper at .claude/scripts/pr-review-daemon.sh that reads plugin_dir from daemon.yaml and execs the plugin script. This keeps mprocs.yaml portable:

# mprocs.yaml (checked into repo — no user-specific paths)
pr-daemon:
  cmd: ["bash", ".claude/scripts/pr-review-daemon.sh"]
  autostart: false
  env:
    POLL_INTERVAL: "300"

Each user sets their plugin path in config:

# ~/.claude/kc-plugins-config/pr-flow/daemon.yaml
plugin_dir: /path/to/kc-pr-flow

Option B — direct (personal use):

cd <project-root>
bash ${CLAUDE_PLUGIN_ROOT}/scripts/pr-review-daemon.sh

Tell the user the plugin path: Read ${CLAUDE_PLUGIN_ROOT}/scripts/pr-review-daemon.sh to get the absolute path.

stop

If running in mprocs: instruct user to press s on the pr-daemon process. If running in terminal: Ctrl+C.

status

Show daemon status from the usage log:

USAGE_LOG="$HOME/.claude/audit/pr-daemon-usage.jsonl"
if [[ -s "$USAGE_LOG" ]]; then
  echo "=== PR Daemon Usage ==="
  jq -rs '{
    total_iterations: length,
    total_cost: ([.[].cost] | add | . * 10000 | round / 10000),
    this_month: ([.[] | select(.ts[:7] == (now | strftime("%Y-%m")))] | {
      iterations: length,
      cost: ([.[].cost] | add | . * 10000 | round / 10000)
    }),
    last_action: (last | {ts, action, cost}),
    actions_taken: ([.[] | select(.action != "" and .action != "Action taken: NONE (all skipped)")] | length)
  }' < "$USAGE_LOG"
else
  echo "No usage data yet. Daemon has not run."
fi

Monthly cost breakdown:

jq -s 'group_by(.ts[:7]) | .[] | {month: .[0].ts[:7], cost: ([.[].cost] | add | . * 100 | round / 100), iters: length}' ~/.claude/audit/pr-daemon-usage.jsonl

config

Read and display current config:

cat ~/.claude/kc-plugins-config/pr-flow/daemon.yaml

Full YAML schema with defaults:

plugin_dir: ""            # absolute path to kc-pr-flow plugin (required for wrapper)
poll_interval: 300        # seconds between iterations (default: 5 min)
model: sonnet             # claude -p model (subagents inherit)
max_turns: 30             # pipe-mode safety valve
ci_gate_context: ci-gate  # commit status context ("none" to skip check)
commit_scope: review      # → fix(review): <description>
slack_webhook: ""         # Slack incoming webhook URL (empty = disabled)
gate_script: ""           # custom pre-flight gate script path (exit 0 = go, 1 = skip)

Environment variable overrides (take precedence over YAML):

Env Var	Overrides	Example
POLL_INTERVAL	poll_interval	POLL_INTERVAL=600 (10 min)
PR_DAEMON_SLACK_WEBHOOK	slack_webhook	Slack incoming webhook URL
PR_DAEMON_GATE	gate_script	Path to custom gate script

To modify: edit ~/.claude/kc-plugins-config/pr-flow/daemon.yaml directly. Changes take effect on next iteration (no restart needed — script re-reads config each loop).

First-time setup (if config directory doesn't exist):

mkdir -p ~/.claude/kc-plugins-config/pr-flow
cat > ~/.claude/kc-plugins-config/pr-flow/daemon.yaml << 'EOF'
poll_interval: 300
model: sonnet
max_turns: 30
ci_gate_context: ci-gate
commit_scope: review
slack_webhook: ""
gate_script: ""
EOF

Troubleshooting

The daemon runs preflight checks on startup. Common errors:

Error	Cause	Fix
ERROR: claude CLI not found in PATH	Non-interactive shell PATH missing claude	Add full path: export PATH="$HOME/.claude/bin:$PATH" in script or mprocs env
ERROR: gh CLI not found in PATH	Same PATH issue for gh	which gh in interactive shell → add that directory to daemon PATH
ERROR: Prompt file not found	Plugin directory moved or broken symlink	Re-check --plugin-dir path or reinstall plugin
Daemon exits immediately	set -euo pipefail + unhandled error	Check stderr output; common: yq not installed (non-fatal, falls back to defaults)
⏭️ No open non-draft PRs every iteration	No actionable PRs or wrong repo	Verify cd <project-root> before starting; check gh pr list in that directory
claude -p exited with code 1	API error, rate limit, or max-turns exceeded	Check Claude API status; reduce max_turns if context overflows
Slack notification not arriving	Webhook URL misconfigured	Test: curl -s -X POST "$WEBHOOK" -H 'Content-Type: application/json' -d '{"text":"test"}'

Daemon always set (not configurable): PR_DAEMON_MODE=1 (bypasses SessionStart superpowers hook) and PR_DAEMON_AUDIT=1 (enables Bash command audit logging via PostToolUse hook).

Prerequisites

• claude CLI in PATH
• gh CLI authenticated
• yq for YAML parsing (optional — falls back to defaults without it)
• terminal-notifier for click-to-open macOS notifications (optional — falls back to osascript)
• jq for JSON processing

Architecture

mprocs / terminal
└── pr-review-daemon.sh (shell while-loop)
    ├── Pre-flight gate (gh pr list + ci-gate check)
    └── claude -p (fresh Sonnet session per iteration)
        ├── Classify PRs (SKIP / STUCK / REVIEW / FIX)
        ├── REVIEW → Skill("kc-pr-flow:kc-pr-review")
        └── FIX → Skill("kc-pr-flow:kc-pr-review-resolve")

Each iteration is stateless. GitHub API is the single source of truth.