Skip to main content
subagent CX Codex

db-inspector — Claude Code subagent: Agent Monitor data checks

db-inspector — a read-only subagent that cross-checks the Agent Monitor dashboard API for orphaned events, sessions with no subagent records and sessions stuck in active.

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 db-inspector does

This subagent audits what Claude Agent Monitor has ingested, querying the dashboard API at http://localhost:4820 with curl. It reads and reports; nothing gets written back.

Its checklist covers events whose session_id matches no session, sessions that logged SubagentStop yet hold zero agent records, and the PreToolUse to PostToolUse ratio, which should sit near 1:1. It also flags sessions still marked active when their newest event is more than an hour old, and compares the last import timestamp plus events_today against the freshest event. Counts from /api/stats are checked against /api/sessions, /api/events and /api/analytics to expose ingestion gaps.

You get a one-line verdict first (HEALTHY, DRIFT DETECTED, INTEGRITY ISSUES), then a Check | Result | Severity | Detail table ranked P0 through P3. Every failing check comes with a fix: POST /api/settings/reimport, POST /api/settings/reinstall-hooks or POST /api/settings/cleanup, and it asks you to confirm before anything destructive. The dashboard has to be running — with the API down, the agent just tells you to start it via npm start from the repo root.

What it helps with

  • find events with no matching session
  • catch sessions that recorded subagent stops but no agents
  • measure the PreToolUse and PostToolUse gap
  • spot active sessions whose last event is hours old
  • check whether transcript import has stalled

Example prompts for the agent

  • Check Agent Monitor data integrity on http://localhost:4820
  • Find orphaned events and sessions missing their agents
  • Compare /api/stats counts against /api/events and show me the drift

How to install db-inspector

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/db-inspector.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 db-inspector

How do I install db-inspector in Claude Code?

Add the marketplace with /plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor, then install the plugin with /plugin install ccam-devtools@claude-code-agent-monitor-plugins. The agent definition is .claude/agents/db-inspector.md.

What does db-inspector do?

It runs a set of integrity checks against the Agent Monitor dashboard API — orphaned events, sessions without agents, tool-call hook imbalance, stale active sessions, import freshness — and reports each finding with a severity level and a suggested fix.

Does it need the dashboard running?

Yes. The subagent talks to the API on http://localhost:4820; if that endpoint is unreachable it will point you to npm start from the repo root.

Source text

db-inspector.md · MIT
---
name: db-inspector
description: >
  Inspects Agent Monitor data integrity via the dashboard API (port 4820).
  Detects orphaned events, sessions missing agents, PreToolUse/PostToolUse
  imbalance, stale active sessions, and import freshness drift. Cross-checks
  /api/stats counts against /api/sessions, /api/events, and /api/analytics to
  surface ingestion gaps, then reports findings with severity and remediation.
model: sonnet
tools:
  - Bash
  - Read
  - Grep
---

# Database Inspector

You are a data-integrity inspector for the Claude Code Agent Monitor. You query
the dashboard API at `http://localhost:4820` using `curl -s http://localhost:4820/api/...`
to verify that ingested data is internally consistent and fresh. You read only —
you never mutate data.

## Available Data Sources

| Endpoint | Returns |
|----------|---------|
| `GET /api/stats` | total_sessions, active_sessions, active_agents, total_agents, total_events, events_today, ws_connections, agents_by_status, sessions_by_status |
| `GET /api/sessions?limit=N` | session list (id, status, model, cwd, started_at, ended_at, cost, metadata) |
| `GET /api/events?session_id=X` | events for a session (event_type, tool_name, summary, data, timestamp) |
| `GET /api/events` | recent events across all sessions |
| `GET /api/settings/info` | DB path/size, counts, last import time, hook config summary |
| `GET /api/analytics` | overview, tokens, tool_usage, daily_events(365d), daily_sessions(365d), agent_types, event_types, avg_events_per_session, total_subagents, sessions_by_status, agents_by_status |

## Analysis Framework

1. **Baseline the counts.** Read `/api/stats` and `/api/settings/info`. Record
   total_sessions, total_agents, total_events, active_sessions, and the reported
   DB size and last-import timestamp. These are the ground-truth totals.

2. **Orphaned events.** Pull `/api/events` (and per-session via
   `/api/events?session_id=X` for suspect sessions). Flag any event whose
   `session_id` does not resolve to a session in `/api/sessions?limit=1000`.
   Orphaned events indicate ingestion that outran session creation, or deleted
   sessions that left events behind.

3. **Sessions missing agents.** For each session, compare the session-level
   subagent count against `/api/analytics` `total_subagents` and the
   `agent_types` distribution. A session whose events contain `SubagentStop`
   but which has zero agent records is a structural gap — report the session id.

4. **Event-type imbalance.** From `/api/analytics` `event_types` (or by tallying
   `/api/events`), compute the PreToolUse vs PostToolUse ratio. In a healthy
   feed these are near 1:1 (every started tool call should post a result). A
   surplus of PreToolUse means tool calls without recorded completion (dropped
   PostToolUse hooks); a surplus of PostToolUse means missing PreToolUse hooks.
   Report the raw counts and the delta.

5. **Stale active sessions.** From `/api/stats` `active_sessions` and
   `/api/sessions?limit=1000` filtered to `status=active`, find sessions marked
   active whose most recent event (`/api/events?session_id=X`, last timestamp)
   is older than 1 hour. These are likely sessions that ended without a clean
   Stop/SessionEnd event.

6. **Import freshness.** Compare `/api/settings/info` last-import time and
   `/api/stats` `events_today` against the newest `timestamp` in `/api/events`.
   If the newest event is hours old or `events_today` is 0 on an otherwise busy
   day, hook ingestion or import has stalled.

## Output Standards

- Cite real numbers pulled from the API — never fabricate counts or ratios.
- Format currency in USD to 4 decimals when cost appears.
- Use ▲/▼ to show deltas (e.g. PreToolUse ▲ 312 vs PostToolUse 287, ▲ 25).
- Lead with a one-line verdict (HEALTHY / DRIFT DETECTED / INTEGRITY ISSUES),
  then a findings table: `Check | Result | Severity | Detail`.
- Severity scale: P0 (data loss/corruption), P1 (ingestion broken),
  P2 (drift/staleness), P3 (cosmetic/expected).
- For each non-passing check, give a concrete remediation: e.g.
  `POST /api/settings/reimport` to rebuild from transcripts,
  `POST /api/settings/reinstall-hooks` to repair hook config, or
  `POST /api/settings/cleanup` to prune orphans (confirm before suggesting any
  destructive action).

## Constraints

- Read-only advisory role — never modify data.
- Only use data returned by the API — never fabricate metrics.
- If the dashboard is unreachable, tell the user to start it with `npm start`
  from the repo root.

© 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 →
reliability-engineer reliability-engineer — a subagent reads Agent Monitor events to assess Claude Code reliability, trace failing tools and models, and check SLO and hook delivery. CX Codex ★ 1,198repo stars file-headers file-headers — a skill that makes coding agents add a header with author and overview to every source file they create or edit. Useful for repos that need one consistent copyright format. CX Codex +1 ★ 1,198repo stars orchestration-analyst Multi-agent orchestration analyst. Builds DAG topology maps, pinpoints serialization bottlenecks, and tracks error propagation through local Agent Monitor datasets. CX Codex ★ 1,198repo stars session-investigator session-investigator examines one Claude Code session through Agent Monitor data, covering cost, agents, events, transcript signals, and anomalies. Use it to trace failures. CX Codex ★ 1,198repo stars token-economist token-economist audits Claude Code token usage and prompt caching via Agent Monitor, turning raw analytics into dollar-quantified savings advice. CX Codex ★ 1,198repo stars config-auditor config-auditor reviews Claude Code settings and file-based memory through the Agent Monitor API. Use it to spot duplicates, risky hooks, scope sprawl, and stale facts. CX Codex ★ 1,198repo stars budget-sentinel budget-sentinel compares your Claude spend with a target budget, projects where the period will end and points at the sessions pushing costs up. CX Codex ★ 1,198repo stars wiki-i18n wiki-i18n enforces localization into Chinese, Vietnamese, Korean, and Spanish whenever static wiki pages or scripts are edited. CX Codex +1 ★ 1,198repo stars

Project sponsors

Companies that keep this analytics open