Skip to main content
debug-mode Enable, disable, and manage debug mode for agentdev sessions.
Records all tool invocations, skill activations, hook triggers, and agent delegations to JSONL.
Use when debugging agent behavior, optimizing workflows, or analyzing session performance.
Ir para a instalação Skills Marketplace Descubra e explore skills de IA criadas pela comunidade.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Mostrar detalhes do prompt Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
npx skills add https://github.com/MadAppGang/claude-code --skill debug-modeO comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.
Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.
Baixar Zip Baixando... Ocupações relacionadas
SOC
Baseado na classificação ocupacional SOC
name debug-mode description Enable, disable, and manage debug mode for agentdev sessions.
Records all tool invocations, skill activations, hook triggers, and agent delegations to JSONL.
Use when debugging agent behavior, optimizing workflows, or analyzing session performance.
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 activelevel: 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 minimalPhase transitions, errors, session start/end standardAll of minimal + tool invocations, agent delegations verboseAll of standard + skill activations, hook triggers, full parameters
Default level is standard.
Changing Debug Level 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
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" : { ... }
}
event_id: Unique UUID for this eventcorrelation_id: Links related events (e.g., tool_invocation -> tool_result)timestamp: ISO 8601 timestamptype: Event type (see below)data: Type-specific payload
Event Types Type Description session_startSession initialization with metadata session_endSession completion tool_invocationTool called with parameters tool_resultTool execution result skill_activationSkill loaded by agent hook_triggerPreToolUse/PostToolUse hook fired agent_delegationTask delegated to sub-agent agent_responseSub-agent returned result phase_transitionWorkflow phase changed user_interactionUser approval/input requested proxy_mode_requestExternal model request via Claudish proxy_mode_responseExternal model response errorError 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:
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:
brew install jq
apt-get install jq
Quick Statistics
cat session.jsonl | jq -s 'group_by(.type) | map({type: .[0].type, count: length})'
Tool Usage Analysis
cat session.jsonl | jq -s '
[.[] | select(.type == "tool_invocation") | .data.tool_name]
| group_by(.)
| map({tool: .[0], count: length})
| sort_by(-.count)'
Failed Operations
cat session.jsonl | jq 'select(.type == "error" or (.type == "tool_result" and .data.success == false))'
Timeline View
cat session.jsonl | jq '"\(.timestamp) [\(.type)] \(.data | keys | join(", "))"'
Event Correlation
INVOCATION_ID="550e8400-e29b-41d4-a716-446655440001"
cat session.jsonl | jq "select(.event_id == \"$INVOCATION_ID \" or .correlation_id == \"$INVOCATION_ID \")"
Phase Duration Analysis
cat session.jsonl | jq -s '
[.[] | select(.type == "phase_transition")]
| sort_by(.timestamp)
| .[]
| {phase: .data.to_name, timestamp: .timestamp}'
Agent Delegation Timing
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
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 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
Check if debug mode is enabled:
/agentdev:debug-status
Verify config file:
cat .claude/agentdev-debug.json
Verify the directory is writable:
ls -la claude-code-session-debug/
jq Commands Not Working
Install jq: brew install jq or apt-get install jq
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:
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:
Install "JSON Lines" VS Code extension
Use "Format Document" on each line individually
Importing to Analytics
cat session.jsonl | jq -rs '
(.[0] | keys_unsorted) as $keys
| ($keys | @csv),
(.[] | [.[$keys[]]] | @csv)' > session.csv
Streaming to External 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-enableEnable debug mode (creates config file) /agentdev:debug-disableDisable debug mode (updates config file) /agentdev:debug-statusCheck current debug mode status
