debug-mode

name	debug-mode
description	Manages agentdev debug mode — records tool, skill, hook, and agent events to JSONL. Use when debugging agent behavior, optimizing workflows, or analyzing session performance.
user-invocable	false

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)

{
  "event_id": "550e8400-e29b-41d4-a716-446655440001",
  "correlation_id": null,
  "timestamp": "2026-01-09T06:40:00Z",
  "type": "tool_invocation",
  "data": { ... }
}

Fields:

• event_id: Unique UUID for this event
• correlation_id: Links related events (e.g., tool_invocation -> tool_result)
• timestamp: ISO 8601 timestamp
• type: Event type (see below)
• data: Type-specific payload

Event Types

Type	Description
session_start	Session initialization with metadata
session_end	Session completion
tool_invocation	Tool called with parameters
tool_result	Tool execution result
skill_activation	Skill loaded by agent
hook_trigger	PreToolUse/PostToolUse hook fired
agent_delegation	Task delegated to sub-agent
agent_response	Sub-agent returned result
phase_transition	Workflow phase changed
user_interaction	User approval/input requested
proxy_mode_request	External model request via Claudish
proxy_mode_response	External model response
error	Error occurred

What Gets Captured

Session Metadata

• Session ID and path
• User request
• Environment (Claudish availability, plugin version)
• Start/end timestamps

Tool Invocations

• Tool name
• Parameters (sanitized - credentials redacted)
• Execution context (phase, agent)
• Duration and result size

Agent Delegations

• Target agent name
• Prompt preview (first 200 chars)
• Proxy mode model if used
• Session path

Proxy Mode

• Model ID
• Request/response duration
• Success/failure status

Phase Transitions

• From/to phase numbers and names
• Transition reason (completed, skipped, failed)
• Quality gate results

Errors

• Error type (tool_error, hook_error, agent_error, etc.)
• Message and stack trace
• Context (phase, agent, tool)
• Recoverability

Sensitive Data Protection

Debug mode automatically sanitizes sensitive data:

Redacted Patterns:

• API keys (sk-*, ghp_*, AKIA*, etc.)
• Tokens (bearer, access, auth)
• Passwords and secrets
• AWS credentials
• Slack tokens (xox*)
• Google API keys (AIza*)

Analyzing Debug Output

Prerequisites

Install jq for JSON processing:

# macOS
brew install jq

# Linux
apt-get install jq

Quick Statistics

# Count events by type
cat session.jsonl | jq -s 'group_by(.type) | map({type: .[0].type, count: length})'

Tool Usage Analysis

# Tool invocation counts
cat session.jsonl | jq -s '
  [.[] | select(.type == "tool_invocation") | .data.tool_name]
  | group_by(.)
  | map({tool: .[0], count: length})
  | sort_by(-.count)'

Failed Operations

# Find all errors and failed tool results
cat session.jsonl | jq 'select(.type == "error" or (.type == "tool_result" and .data.success == false))'

Timeline View

# Chronological event summary
cat session.jsonl | jq '"\(.timestamp) [\(.type)] \(.data | keys | join(", "))"'

Event Correlation

# Find tool invocation and its result
INVOCATION_ID="550e8400-e29b-41d4-a716-446655440001"
cat session.jsonl | jq "select(.event_id == \"$INVOCATION_ID\" or .correlation_id == \"$INVOCATION_ID\")"

Phase Duration Analysis

# Calculate time between phase transitions
cat session.jsonl | jq -s '
  [.[] | select(.type == "phase_transition")]
  | sort_by(.timestamp)
  | .[]
  | {phase: .data.to_name, timestamp: .timestamp}'

Agent Delegation Timing

# Find slowest agent delegations
cat session.jsonl | jq -s '
  [.[] | select(.type == "agent_response")]
  | sort_by(-.data.duration_ms)
  | .[:5]
  | .[]
  | {agent: .data.agent, duration_sec: (.data.duration_ms / 1000)}'

Proxy Mode Performance

# External model response times
cat session.jsonl | jq -s '
  [.[] | select(.type == "proxy_mode_response")]
  | .[]
  | {model: .data.model_id, success: .data.success, duration_sec: (.data.duration_ms / 1000)}'

Disabling Debug Mode

Use the command:

/agentdev:debug-disable

Or manually update:

jq '.enabled = false' .claude/agentdev-debug.json > tmp.json && mv tmp.json .claude/agentdev-debug.json

Or delete the config file:

rm -f .claude/agentdev-debug.json

Cleaning Up Debug Files

Remove All Debug Files

rm -rf claude-code-session-debug/

Remove Files Older Than 7 Days

find claude-code-session-debug/ -name "*.jsonl" -mtime +7 -delete

Remove Files Larger Than 10MB

find claude-code-session-debug/ -name "*.jsonl" -size +10M -delete

File Permissions

Debug files are created with restrictive permissions:

• Directory: 0o700 (owner only)
• Files: 0o600 (owner read/write only)

This prevents other users from reading potentially sensitive session data.

Example Session Output

{"event_id":"init-1736408183","timestamp":"2026-01-09T06:36:23Z","type":"session_start","data":{"schema_version":"1.0.0","session_id":"agentdev-graphql-reviewer-20260109-063623-ba71","user_request":"Create an agent that reviews GraphQL schemas","session_path":"ai-docs/sessions/agentdev-graphql-reviewer-20260109-063623-ba71","environment":{"claudish_available":true,"plugin_version":"1.4.0","jq_available":true}}}
{"event_id":"550e8400-e29b-41d4-a716-446655440001","timestamp":"2026-01-09T06:36:25Z","type":"tool_invocation","data":{"tool_name":"TodoWrite","parameters":{"todos":"[REDACTED]"},"context":{"phase":0,"agent":null}}}
{"event_id":"550e8400-e29b-41d4-a716-446655440002","correlation_id":"550e8400-e29b-41d4-a716-446655440001","timestamp":"2026-01-09T06:36:25Z","type":"tool_result","data":{"tool_name":"TodoWrite","success":true,"result_size_bytes":156,"duration_ms":12}}
{"event_id":"550e8400-e29b-41d4-a716-446655440003","timestamp":"2026-01-09T06:36:26Z","type":"phase_transition","data":{"from_phase":null,"to_phase":0,"from_name":null,"to_name":"Init","transition_reason":"completed","quality_gate_result":true}}
{"event_id":"550e8400-e29b-41d4-a716-446655440004","timestamp":"2026-01-09T06:36:30Z","type":"agent_delegation","data":{"target_agent":"agentdev:architect","prompt_preview":"SESSION_PATH: ai-docs/sessions/agentdev-graphql-reviewer...","prompt_length":1456,"proxy_mode":null,"session_path":"ai-docs/sessions/agentdev-graphql-reviewer-20260109-063623-ba71"}}
{"event_id":"end-1736408565","timestamp":"2026-01-09T06:42:45Z","type":"session_end","data":{"success":true}}

Troubleshooting

Debug File Not Created

1. Check if debug mode is enabled:

   /agentdev:debug-status
   

2. Verify config file:

   cat .claude/agentdev-debug.json
   

3. Verify the directory is writable:

   ls -la claude-code-session-debug/
   

jq Commands Not Working

1. Install jq: brew install jq or apt-get install jq
2. Verify JSONL format (each line should be valid JSON):

   head -1 session.jsonl | jq .
   

Large Debug Files

Debug files can grow large in verbose mode. Use minimal level for lighter capture:

Update config:

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

Or clean up old files regularly:

find claude-code-session-debug/ -name "*.jsonl" -mtime +3 -delete

Integration with Other Tools

Viewing in VS Code

The JSONL format works with JSON syntax highlighting. For better viewing:

1. Install "JSON Lines" VS Code extension
2. Use "Format Document" on each line individually

Importing to Analytics

# Convert to CSV for spreadsheet import
cat session.jsonl | jq -rs '
  (.[0] | keys_unsorted) as $keys
  | ($keys | @csv),
  (.[] | [.[$keys[]]] | @csv)' > session.csv

Streaming to External Service

# Tail and send to logging service
tail -f session.jsonl | while read line; do
  curl -X POST -d "$line" https://logging.example.com/ingest
done

Commands Reference

Command	Description
/agentdev:debug-enable	Enable debug mode (creates config file)
/agentdev:debug-disable	Disable debug mode (updates config file)
/agentdev:debug-status	Check current debug mode status