Skip to main content

Debugging Playbook

Operational guide for inspecting execution state and debugging workflows.

CLI Commands

# List all executions
smithers db executions

# List executions for a specific workflow
smithers db executions --source my-workflow.tsx

# View execution details
smithers db execution <execution-id>

# View current state
smithers db state

# View state for specific execution
smithers db state --execution <execution-id>

# View database statistics
smithers db stats

Inspecting State

View Phase Progress

# Using SQLite directly
sqlite3 .smithers/my-workflow/db.sqlite "SELECT * FROM phases ORDER BY created_at"

View Step Progress

sqlite3 .smithers/my-workflow/db.sqlite "SELECT * FROM steps ORDER BY created_at"

View Running Tasks

sqlite3 .smithers/my-workflow/db.sqlite "SELECT * FROM tasks WHERE status = 'running'"

View State History

sqlite3 .smithers/my-workflow/db.sqlite "SELECT * FROM state ORDER BY updated_at DESC"

Claude Code Logs

Claude execution logs are stored at:
~/.claude/projects/<project-path>/sessions/
Each session contains:
  • session.jsonl - Full conversation log
  • metadata.json - Session metadata

Correlating Logs to Executions

// Log session IDs in your workflow
<Claude
  onFinished={(result) => {
    console.log("Session:", result.sessionId);
  }}
>
Find the session:
ls -la ~/.claude/projects/*/sessions/ | grep <session-id>

Common Issues

Workflow Stalls

Symptom: Orchestration stops advancing. Causes:
  1. No state change in onFinished callback
  2. Untracked async work completing after task check
  3. Missing task completion call
Debug:
# Check for stuck tasks
sqlite3 .smithers/my-workflow/db.sqlite "SELECT * FROM tasks WHERE status = 'running'"

# Check last state change
sqlite3 .smithers/my-workflow/db.sqlite "SELECT * FROM state ORDER BY updated_at DESC LIMIT 5"

Phase Not Advancing

Symptom: Phase stuck, next phase never starts. Causes:
  1. Step not completing
  2. No Steps in Phase (see Phase docs)
  3. skipIf returning wrong value
Debug:
# Check step status
sqlite3 .smithers/my-workflow/db.sqlite "SELECT * FROM steps WHERE phase_id = '<phase-id>'"

Crash Recovery Not Working

Symptom: Workflow restarts from beginning. Causes:
  1. Using useState instead of SQLite state
  2. Not checking db.execution.findIncomplete()
  3. Database not persisted (in-memory mode)
Fix: Ensure all state uses db.state and execution resume logic is present:
const incomplete = await db.execution.findIncomplete();
if (incomplete) {
  executionId = incomplete.id;
}

Database Schema

Key tables for debugging:
TablePurpose
executionsWorkflow run records
stateKey-value state storage
phasesPhase progress tracking
stepsStep completion tracking
tasksAsync task tracking
agentsAgent execution logs