clawdoc#

Examine agent sessions. Diagnose failures. Prescribe fixes.

Invocation modes#

/clawdoc (slash command — default: headline mode)#

Produces a compact, tweetable health check:

text

🩻 clawdoc — 3 findings across 12 sessions (last 7 days)
💸 $47.20 spent — $31.60 was waste (67% recoverable)
🔴 Retry loop on exec burned $18.40 in one session
🟡 Opus running 34 heartbeats ($8.20 → $0.12 on Haiku)
🟡 SOUL.md is 9,200 tokens — 14% of your context window

Run: bash {baseDir}/scripts/headline.sh ~/.openclaw/agents/main/sessions

/clawdoc full or "give me a full diagnosis"#

Runs all 14 pattern detectors and produces the complete diagnosis report with evidence and prescriptions.

/clawdoc brief or "clawdoc one-liner for daily brief"#

Single-line summary for morning cron integration:

text

Yesterday: 8 sessions, $3.40, 1 warning (cron context growth on daily-report)

Run: bash {baseDir}/scripts/headline.sh --brief ~/.openclaw/agents/main/sessions

Natural language triggers#

Also activates when user says: "what went wrong", "why did that fail", "debug", "diagnose", "why was that so expensive", "where are my tokens going", "cost breakdown", "health check", "check my agent", "what's wrong", "examine"

Quick examination — most recent session#

Find the most recent session file and run:

text

bash {baseDir}/scripts/examine.sh <session.jsonl>

This outputs a JSON summary with turns, cost, token counts, tool call frequency, and error count.

Single-session diagnosis#

Run all 14 pattern detectors against a specific session file:

text

bash {baseDir}/scripts/diagnose.sh <session.jsonl> | jq .

Diagnosis with prescriptions#

Pipe diagnose output into prescribe for a formatted report with fix recommendations:

text

bash {baseDir}/scripts/diagnose.sh <session.jsonl> | bash {baseDir}/scripts/prescribe.sh

Cost breakdown#

Show per-turn cost waterfall for a session:

text

bash {baseDir}/scripts/cost-waterfall.sh <session.jsonl> | jq '.[0:5]'

Cross-session pattern recurrence#

Analyze pattern recurrence across multiple sessions in a directory:

text

bash {baseDir}/scripts/history.sh <sessions-dir> | jq .

Full diagnosis#

When the user wants a comprehensive diagnosis, run the scripts above and synthesize findings into this report format:

Diagnosis report format#

text

## 🩻 Diagnosis — [date]

### Patient summary
- Sessions examined: N
- Period: [date range]
- Total spend: $X.XX
- Total tokens: XXk in / XXk out

### Findings

#### 🔴 Critical
[Infinite retry loops, context exhaustion, tool-as-text failures]
Each finding includes: what happened, evidence, estimated cost impact, and specific prescription.

#### 🟡 Warning
[Cost spikes, model routing waste, cron accumulation, compaction damage, workspace overhead]

#### 🟢 Healthy
[What's working well — efficient sessions, good model routing]

### Prescriptions (ranked by cost impact)
1. [Highest-impact fix with specific config change or command]
2. [Second highest]
3. [Third]

### Cost breakdown
[Per-day costs for the examination period]
[Top 3 most expensive sessions with root cause]

Pattern reference#

#PatternSeverityKey indicator1Infinite retry loop🔴 CriticalSame tool called 5+ times consecutively2Non-retryable error retried🔴 HighValidation error → identical retry3Tool calls as text🔴 HighTool names in assistant text, no toolCall blocks4Context window exhaustion🟡-🔴inputTokens > 70% of contextTokens5Sub-agent replay🟡 MediumDuplicate completion messages in parent6Cost spike🟡-🔴Session cost > 2x rolling average7Skill selection miss🟢 Low"command not found" after skill activation8Model routing waste🟡 MediumPremium model on heartbeat/cron9Cron context accumulation🟡 MediumGrowing inputTokens across cron runs10Compaction damage🟡 MediumPost-compaction tool call repetition11Workspace token overhead🟡 MediumBaseline > 15% of context window12Task drift🟡 MediumPost-compaction directory divergence or 10+ reads without edits13Unbounded walk🟠 HighRepeated unscoped find/grep -r flooding output14Tool misuse🟡 MediumSame file read 3+ times without edit, or identical search repeated

Self-improving-agent integration#

To enable writing findings to .learnings/LEARNINGS.md, set CLAWDOC_LEARNINGS=1 before running prescribe:

text

CLAWDOC_LEARNINGS=1 bash {baseDir}/scripts/diagnose.sh <session.jsonl> | bash {baseDir}/scripts/prescribe.sh

Tips#

• Session JSONL files are the ground truth for all diagnostics
• Use jq -s (slurp) for aggregations across all lines in a session file
• Filter message.content[] by type=="text" for readable content, type=="toolCall" for tool invocations
• When prescribing config changes, always show the exact JSON path and value