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 (v1.0.0) ```json { "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: ```bash # macOS brew install jq # Linux apt-get install jq ``` ### Quick Statistics ```bash # Count events by type cat session.jsonl | jq -s 'group_by(.type) | map({type: .[0].type, count: length})' ``` ### Tool Usage Analysis ```bash # 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 ```bash # Find all errors and failed tool results cat session.jsonl | jq 'select(.type == "error" or (.type == "tool_result" and .data.success == false))' ``` ### Timeline View ```bash # Chronological event summary cat session.jsonl | jq '"\(.timestamp) [\(.type)] \(.data | keys | join(", "))"' ``` ### Event Correlation ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash jq '.enabled = false' .claude/agentdev-debug.json > tmp.json && mv tmp.json .claude/agentdev-debug.json ``` Or delete the config file: ```bash rm -f .claude/agentdev-debug.json ``` ## Cleaning Up Debug Files ### Remove All Debug Files ```bash rm -rf claude-code-session-debug/ ``` ### Remove Files Older Than 7 Days ```bash find claude-code-session-debug/ -name "*.jsonl" -mtime +7 -delete ``` ### Remove Files Larger Than 10MB ```bash 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 ```jsonl {"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: ```bash /agentdev:debug-status ``` 2. Verify config file: ```bash cat .claude/agentdev-debug.json ``` 3. Verify the directory is writable: ```bash 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): ```bash head -1 session.jsonl | jq . ``` ### Large Debug Files Debug files can grow large in verbose mode. Use `minimal` level for lighter capture: Update config: ```bash jq '.level = "minimal"' .claude/agentdev-debug.json > tmp.json && mv tmp.json .claude/agentdev-debug.json ```