Skip to main content
subagent CX Codex

issue-triager — Claude Code subagent: triage and fix issues

issue-triager diagnoses Claude Code Agent Monitor failures across the Express API, SQLite store, and hooks, returning concrete remediation steps.

MIT ★ 1,198 updated 2026-10-23

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-devtools@claude-code-agent-monitor-plugins
Open on GitHub

What issue-triager does

This subagent troubleshoots outages and anomalies across the Claude Code Agent Monitor stack. It runs systematic checks against the Express server on port 4820, the SQLite database running better-sqlite3 with WAL enabled, the WebSocket broadcast layer, and scripts/hook-handler.js handling 7 event types. It also checks the transcript cache and the MCP server setup.

Under the hood, it operates on the sonnet model with direct access to Bash, Read, and Grep. The triager issues commands like curl -sf http://localhost:4820/api/health, reads ~/.claude/settings.json, and verifies data/dashboard.db directly on disk. Identified issues are tagged with severity levels ranging from P0 (system unusable) to P3 (minor visual glitch).

Each investigation ends with a structured summary containing root cause analysis, factual evidence, exact repair instructions, and prevention tips. Without a local Node.js environment and active port access, its network verification commands will fail.

What it helps with

  • pinpoint why the Agent Monitor Express API fails on port 4820
  • validate Claude Code hook settings inside settings.json
  • trace missing event ingestion in the SQLite database
  • classify monitor incidents from P0 critical to P3 low

Example prompts for the agent

  • Run issue-triager to find out why Agent Monitor is not receiving hook events
  • Ask issue-triager to inspect Express API health on port 4820 and verify the database
  • Have issue-triager check ~/.claude/settings.json for broken hook handlers

How to install issue-triager

1Plugin marketplace

/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-devtools@claude-code-agent-monitor-plugins

2Manually: put the files in place

.claude/agents/issue-triager.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about issue-triager

How to install issue-triager in Claude Code?

Run /plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor followed by /plugin install ccam-devtools@claude-code-agent-monitor-plugins, or place the file directly at .claude/agents/issue-triager.md.

What does issue-triager do?

It diagnoses problems inside the Agent Monitor system, inspects API endpoints and database health, and formats fixes by severity.

Which components does issue-triager inspect?

It inspects the Express API on port 4820, SQLite database, WebSocket broadcast, hook handler script, transcript cache, and the MCP server.

Source text

issue-triager.md · MIT
---
name: issue-triager
description: >
  Triages Agent Monitor issues by systematically checking the Express API
  (port 4820), SQLite database (better-sqlite3 with WAL mode), WebSocket
  broadcast, hook handler (scripts/hook-handler.js processing 7 event types),
  transcript cache (LRU max 200 with stat-based incremental reads), and
  the MCP server. Classifies by severity and provides specific remediation.
model: sonnet
tools:
  - Bash
  - Read
  - Grep
---

# Issue Triager

You are a technical issue triager for the Claude Code Agent Monitor system.
When users report problems, you systematically investigate, classify, and
provide resolution guidance.

## System Architecture

The Agent Monitor has these components:
- **Server** (`server/`): Express API on port 4820
- **Database** (`data/dashboard.db`): SQLite via better-sqlite3
- **WebSocket** (`server/websocket.js`): Real-time event broadcast
- **Hook Handler** (`scripts/hook-handler.js`): Receives Claude Code hook events
- **Hook Installer** (`scripts/install-hooks.js`): Configures hooks in `~/.claude/settings.json`
- **Client** (`client/`): React + Vite SPA on port 5173 (dev) or served by Express (prod)
- **MCP Server** (`mcp/`): Model Context Protocol integration

## Investigation Process

1. **Symptom Collection**: Understand what the user is experiencing
2. **Component Identification**: Determine which component(s) are involved
3. **Evidence Gathering**: Use API calls, file checks, and log inspection
4. **Root Cause Analysis**: Trace the issue to its source
5. **Resolution**: Provide specific fix instructions

## Diagnostic Commands

```bash
# API health
curl -sf http://localhost:4820/api/health

# Check if server is running
lsof -i :4820

# Database status
ls -la data/dashboard.db

# Hook configuration
cat ~/.claude/settings.json | jq '.hooks'

# Recent events
curl -sf 'http://localhost:4820/api/events?limit=10'

# Server logs (if running in foreground)
# Check process stderr/stdout

# Node.js version
node --version
```

## Severity Classification

- **P0 Critical**: System completely non-functional (server won't start, database corrupted)
- **P1 High**: Major feature broken (events not ingesting, WebSocket disconnected)
- **P2 Medium**: Feature degraded (slow queries, stale sessions, missing some events)
- **P3 Low**: Minor issue (UI glitch, cosmetic problem, documentation gap)

## Output Format

For each triaged issue, provide:

```
┌─────────────────────────────────────────┐
│ Issue: [Brief title]                     │
│ Severity: P[0-3] [Critical/High/Med/Low] │
│ Component: [server/client/hooks/db/mcp]  │
│ Status: [investigating/identified/fixed]  │
└─────────────────────────────────────────┘

Root Cause: [Concise explanation]

Evidence:
  1. [Specific observation]
  2. [Specific observation]

Resolution:
  1. [Step-by-step fix]
  2. [Verification step]

Prevention:
  - [How to avoid in future]
```

© Son Nguyen · MIT · hoangsonww/Claude-Code-Agent-Monitor

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set155

The whole set →
fleet-runs fleet-runs — a skill for Claude Code and Codex that reads Workflow fleet run journals from the Agent Monitor and displays run status with per-agent breakdown. CX Codex +1 ★ 1,198repo stars transcript-replay transcript-replay walks Claude Code session transcripts turn-by-turn from Agent Monitor data, summarizing user prompts, assistant decisions, and tool executions. CX Codex +1 ★ 1,198repo stars delegation-audit delegation-audit is a Claude Code skill that reviews which models handled each subagent type and how those assignments performed. It flags weak results, repeated failures, and possible model mismatches. CX Codex +1 ★ 1,198repo stars error-propagation error-propagation finds the depth in a multi-agent tree where a failure started and tracks the chain that carried it up to parent agents. CX Codex +1 ★ 1,198repo stars insights-advisor insights-advisor is a Claude Code subagent that examines Agent Monitor data and connects patterns across sessions. It runs for investigations into agent workflows, model costs, and errors. CX Codex ★ 1,198repo stars focus-analyst focus-analyst turns Agent Monitor session data into a focus profile: turn length, reasoning depth, idle gaps. Then it suggests 1–3 deep-work blocks for the week. CX Codex ★ 1,198repo stars i18n-parity i18n-parity enforces identical localization coverage across all supported locales in the same pull request, preventing incomplete translations. CX Codex +1 ★ 1,198repo stars trend-forecaster The trend-forecaster subagent projects Claude Code usage and spend from Agent Monitor history. Use it to check expected activity and cost over the coming weeks. CX Codex ★ 1,198repo stars

Project sponsors

Companies that keep this analytics open