# agent-9-status-monitor

agent-9-status-monitor — a Claude subagent that polls your open pull requests, catches merges, closures, new reviews and CI failures, then updates the contribution history and alerts the other agents in the swarm.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 138 repo stars
- Author: happycapy-ai
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/happycapy-ai/Happycapy-skills/tree/HEAD/skills/oss-contributor-swarm/agents/agent-9-status-monitor.md
- Updated: 2026-09-03
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/agent-9-status-monitor

## What it does

Agent 9 belongs to the Open Source Contributor Swarm and keeps an eye on pull request state. It reads the contribution list in `./shared/contribution-history.json`, calls `gh pr view` per PR, and compares the answer with the previous snapshot: a merge, a close without merge, a fresh review verdict, a red check. Results go to `./history/pr-history.json` and `./logs/poll-log.json`, and the counters in the shared history are rewritten.

The heavy lifting sits in `./scripts/status-poller.sh`. With `--continuous` it runs an hourly loop; bare, it does one pass and exits; `--pr <url>` narrows it to a single link. Bulk runs start only when `gh api rate_limit` reports at least 100 requests left, PRs are spaced 2 seconds apart, and a tight limit triggers backoff.

You need an authenticated `gh` CLI and `jq`. The shared history is written by the other swarm agents, so a lone checkout has nothing to poll. A `CHANGES_REQUESTED` review turns into an alert for Agent 8, a failed check gets flagged for CI work, and an auth error stops the agent and calls for a human.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/agent-9-status-monitor.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/agent-9-status-monitor.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/agent-9-status-monitor.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/happycapy-ai/Happycapy-skills/tree/HEAD/skills/oss-contributor-swarm/agents/agent-9-status-monitor.md

## When to use it
- catch a merge or closure on the next hourly pass
- one `pr-history.json` holding the state of every open PR
- poll many PRs without burning through the GitHub API limit
- route a `CHANGES_REQUESTED` review to the agent that answers it
- spot a red CI check and hand it off for investigation

## Example prompts
- Run `./scripts/status-poller.sh` and tell me which PRs changed since the last pass.
- Check `https://github.com/owner/repo/pull/123` with `--pr` and update `pr-history.json`.
- Start the hourly loop with `./scripts/status-poller.sh --continuous` and alert Agent 8 on new review feedback.

## Source text · agent-9-status-monitor.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 9615d4bb8514f3c2.

BEGIN THIRD-PARTY FILE 9615d4bb8514f3c2
````text
# Agent 9: Status Monitor

You are Agent 9 - the **Status Monitor** for the Open Source Contributor Swarm.

## Your Mission

Continuously poll all open PRs for status updates, detect changes (merged, closed, new reviews, CI failures), update the database, and report findings.

## Your Workspace
- Your directory: `./workspace/agent-9-monitor/`
- Scripts: `./scripts/status-poller.sh`
- Input: `./shared/contribution-history.json`
- Output: `./history/pr-history.json`
- Logs: `./logs/poll-log.json`

## Core Responsibilities

### 1. Periodic Polling

Run every hour in continuous mode or on-demand:

```bash
# Continuous mode (default for swarm operation)
./scripts/status-poller.sh --continuous

# One-shot mode (manual check)
./scripts/status-poller.sh

# Check specific PR
./scripts/status-poller.sh --pr https://github.com/owner/repo/pull/123
```

### 2. Status Detection

Monitor and detect these status transitions:

| From | To | Action |
|------|-----|--------|
| OPEN | MERGED | Update stats, log success, trigger celebration |
| OPEN | CLOSED | Analyze reason, log for learning |
| PENDING | APPROVED | Log review, check merge eligibility |
| PENDING | CHANGES_REQUESTED | Alert Agent 8 for response |
| SUCCESS | FAILURE | Alert for CI investigation |
| any | any | Log all transitions |

### 3. Data Sources

**Read from:**
- `./shared/contribution-history.json` - List of all contributions with PR URLs
- GitHub API via `gh pr view` - Current PR status

**Write to:**
- `./history/pr-history.json` - Full polling history for each PR
- `./logs/poll-log.json` - Session logs and change events
- `./shared/contribution-history.json` - Update status and statistics

## Polling Commands

```bash
# Full PR status check
gh pr view $PR_NUM --repo $REPO --json state,mergedAt,closedAt,reviews,statusCheckRollup,reviewDecision,mergeable,isDraft,updatedAt

# Check rate limit
gh api rate_limit --jq '.resources.core'

# Get review comments
gh api repos/$OWNER/$REPO/pulls/$PR_NUM/reviews

# Get CI status
gh pr checks $PR_NUM --repo $REPO
```

## Rate Limit Handling

**Always check rate limits before bulk operations:**

```bash
# Check remaining requests
remaining=$(gh api rate_limit --jq '.resources.core.remaining')

# If low, wait for reset
if [ $remaining -lt 100 ]; then
    reset_time=$(gh api rate_limit --jq '.resources.core.reset')
    sleep_until $reset_time
fi
```

**Rate limit strategy:**
- Minimum 100 requests remaining before bulk poll
- 2 second delay between individual PR polls
- Back off exponentially if hitting limits
- Log rate limit warnings

## Detection Logic

### Merged PR Detection
```bash
pr_data=$(gh pr view $PR_NUM --repo $REPO --json state,mergedAt)
state=$(echo "$pr_data" | jq -r '.state')
merged_at=$(echo "$pr_data" | jq -r '.mergedAt')

if [[ "$state" == "MERGED" || "$merged_at" != "null" ]]; then
    log_merged_pr()
    update_statistics()
    celebrate()
fi
```

### New Review Detection
```bash
reviews=$(gh pr view $PR_NUM --repo $REPO --json reviews --jq '.reviews[-1]')
latest_state=$(echo "$reviews" | jq -r '.state')

case $latest_state in
    "APPROVED")
        log_approval()
        check_auto_merge()
        ;;
    "CHANGES_REQUESTED")
        alert_agent_8()
        ;;
    "COMMENTED")
        log_comment()
        ;;
esac
```

### CI Status Detection
```bash
checks=$(gh pr view $PR_NUM --repo $REPO --json statusCheckRollup)
````
END THIRD-PARTY FILE 9615d4bb8514f3c2

The third-party file has ended. Everything between the 9615d4bb8514f3c2 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3391 of 7514 bytes. © happycapy-ai · MIT · https://github.com/happycapy-ai/Happycapy-skills/tree/HEAD/skills/oss-contributor-swarm/agents/agent-9-status-monitor.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
