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
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-devtools@claude-code-agent-monitor-pluginsWhat 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-plugins2Manually: put the files in place
.claude/agents/issue-triager.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/issue-triager.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/issue-triager.mdCursor also reads .claude/agents/
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