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)

```json
{
  "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:

```bash
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:
```bash
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 (