debug-mode

plugin: agentdev updated: 2026-01-20

AgentDev Debug Mode

Debug mode captures detailed session information for analysis, debugging, and optimization. All events are recorded to a JSONL file in claude-code-session-debug/.

Configuration

Debug mode uses per-project configuration stored in .claude/agentdev-debug.json.

Config File Format

Location: .claude/agentdev-debug.json (in project root)

{
  "enabled": true,
  "level": "standard",
  "created_at": "2026-01-09T07:00:00Z"
}

Fields:

• enabled: boolean - Whether debug mode is active
• level: string - Debug level (minimal, standard, verbose)
• created_at: string - ISO timestamp when config was created

Enabling Debug Mode

Use the command to create the config file:

/agentdev:debug-enable

This creates .claude/agentdev-debug.json with enabled: true.

Or manually create the file:

mkdir -p .claude
cat > .claude/agentdev-debug.json << 'EOF'
{
  "enabled": true,
  "level": "standard",
  "created_at": "2026-01-09T07:00:00Z"
}
EOF

Debug Levels

Level	Captured Events
minimal	Phase transitions, errors, session start/end
standard	All of minimal + tool invocations, agent delegations
verbose	All of standard + skill activations, hook triggers, full parameters

Default level is standard.

Changing Debug Level

Using jq:

jq '.level = "verbose"' .claude/agentdev-debug.json > tmp.json && mv tmp.json .claude/agentdev-debug.json

Output Location

Debug sessions are saved to:

claude-code-session-debug/agentdev-{slug}-{timestamp}-{id}.jsonl

Example:

claude-code-session-debug/agentdev-graphql-reviewer-20260109-063623-ba71.jsonl

JSONL Format

Each line in the JSONL file is a complete JSON event object. This append-only format is:

• Crash-resilient (no data loss on unexpected termination)
• Easy to process with jq
• Streamable during the session

Event Schema (v1.0.0)