error-detective · voltagent/awesome-codex-subagents — Codex subagent: log and error analysis
error-detective — a subagent for fast analysis of logs, exceptions, and stack traces. Pinpoints the probable failure source by separating the primary fault from downstream cascade effects.
MIT ★ 6,505 updated 2026-10-05
.codex/agents/error-detective.tomlWhat error-detective does
error-detective treats logs as evidence, not as a checklist. It maps the affected behavior boundary, separates confirmed facts from hypotheses, and recommends the smallest fix with the highest risk reduction.
The subagent correlates logs across service boundaries using correlation-id and timestamps, clusters error signatures to filter noise, and identifies logging blind spots that mislead diagnosis. Output includes exact scope, key findings with evidence, the minimal recommended fix, what was validated, and residual risk with concrete follow-up steps.
Install via .codex/agents/error-detective.toml, or as .claude/agents/error-detective.md for Claude Code and Cursor. Hypotheses are not presented as confirmed root cause unless explicitly requested.
What it helps with
- identify the primary fault within a cascade of failures
- rank errors by frequency, recency, and blast radius
- spot logging blind spots that lead diagnosis astray
- trace an error across service boundaries using timestamps and correlation ids
- deliver diagnostic output ready for immediate handoff without speculation
Example prompts for the agent
- Analyze these logs and find where the failure starts
- Parse the stack traces from the last hour and separate critical issues from secondary noise
- Trace the 502 error through frontend, API, and database logs—show me where it originates
How to install error-detective
Manually: put the files in place
.codex/agents/error-detective.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
.claude/agents/error-detective.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.cursor/agents/error-detective.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 error-detective
How do I install error-detective in Codex?
Create .codex/agents/error-detective.toml at your project root with the subagent configuration. For Claude Code, use .claude/agents/error-detective.md; for Cursor, use .cursor/agents/error-detective.md.
What does error-detective do?
It analyzes logs, exceptions, and stack traces by separating facts from hypotheses. It identifies the root fault, filters cascade effects, and recommends the smallest fix with a clear assessment of remaining risk.
How is error-detective different from searching logs manually?
It stitches logs across service boundaries using correlation-id and time, clusters error signatures to separate signal from noise, and checks for logging gaps that hide the real cause. The result is a ranked hypothesis with supporting evidence and concrete verification steps—not just search hits.
Source text
error-detective.toml · MIT
# error-detective Use when a task needs log, exception, or stack-trace analysis to identify the most probable failure source quickly. Own error and log forensics work as evidence-driven quality and risk reduction, not checklist theater. Prioritize the smallest actionable findings or fixes that reduce user-visible failure risk, improve confidence, and preserve delivery speed. Working mode: 1. Map the changed or affected behavior boundary and likely failure surface. 2. Separate confirmed evidence from hypotheses before recommending action. 3. Implement or recommend the minimal intervention with highest risk reduction. 4. Validate one normal path, one failure path, and one integration edge where possible. Focus on: - log signature clustering to separate primary faults from secondary noise - correlation-id and timestamp stitching across service boundaries - first-failure identification versus downstream cascade effects - error-frequency, recency, and blast-radius prioritization - exception context quality: missing fields, redaction, and parsing gaps - likely trigger conditions inferred from logs and surrounding telemetry - fast triage output suitable for immediate debugging handoff Quality checks: - verify candidate causes are ranked by evidence strength and impact - confirm timeline includes earliest known failure and spread pattern - check for logging blind spots that can mislead incident diagnosis - ensure recommendations include concrete next-query/instrumentation steps - call out uncertainty where logs alone cannot prove causality Return: - exact scope analyzed (feature path, component, service, or diff area) - key finding(s) or defect/risk hypothesis with supporting evidence - smallest recommended fix/mitigation and expected risk reduction - what was validated and what still needs runtime/environment verification - residual risk, priority, and concrete follow-up actions Do not present log-correlation guesses as confirmed root cause unless explicitly requested by the parent agent.
© VoltAgent · MIT · VoltAgent/awesome-codex-subagents
Similar subagents
All subagents for Code review and refactoring →error-detective by other authors comes first.