context-doctor
Visualize and diagnose OpenClaw context window usage. Generates a terminal-rendered breakdown showing workspace files (status, chars, tokens), installed skills inventory, and token budget allocation across bootstrap components. Use when: (1) user asks about context window health or token usage, (2) debugging agent quality degradation ("agent got dumber"), (3) after editing workspace files to verify impact, (4) auditing bootstrap overhead. NOT for: conversation history analysis, model selection, or cost tracking.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/jzocb--context-doctor)HTML
<a href="/listings/jzocb--context-doctor"><img src="/api/listings/jzocb--context-doctor/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
clawhub install context-doctor
Or clone this repo into your workspace skills directory:
git clone https://github.com/jzOcb/context-doctor.git ~/.openclaw/workspace/skills/context-doctor
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 71 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: context-doctor
- description: >
- Visualize and diagnose OpenClaw context window usage. Generates a terminal-rendered
- breakdown showing workspace files (status, chars, tokens), installed skills inventory,
- and token budget allocation across bootstrap components. Use when: (1) user asks about
- context window health or token usage, (2) debugging agent quality degradation ("agent
- got dumber"), (3) after editing workspace files to verify impact, (4) auditing bootstrap
- overhead. NOT for: conversation history analysis, model selection, or cost tracking.
- ---
- # Context Doctor
- Diagnose and visualize how the context window budget is allocated.
- ## Quick Start
- Run the visualization script:
- ```bash
- python3 scripts/context-doctor.py
- ```
- The script auto-detects:
- - Workspace path (`~/.openclaw/workspace` or `OPENCLAW_WORKSPACE` env)
- - OpenClaw version (via `openclaw --version`)
- - Installed skills (system + workspace)
- - Bootstrap file sizes and status
- ## Output Sections
- ### 1. Workspace Files
- Shows each bootstrap file with:
- - **Status**: ✓ OK / ✗ MISSING / ⚠ TRUNCATED (symlink target missing = MISSING)
- - **Characters & Tokens**: Raw size and estimated token count (chars/4)
- - **Visual bar**: Proportional to file size
- ### 2. Installed Skills
- Lists all discovered SKILL.md files from system and workspace skill directories.
- Skills are loaded on-demand, not in bootstrap — shown for awareness only.
- ### 3. Token Budget
- Breaks down bootstrap overhead:
- - System Prompt (framework)
- - Workspace Files (from scan)
- - Skills List (metadata descriptions)
- - Tool Schemas + Summaries
- Shows total bootstrap % vs free conversation space.
- ## Diagnostic Signals
- | Signal | Meaning | Action |
- |--------|---------|--------|
- | 🔴 TRUNCATED | File exceeded max chars, silently cut | Reduce file size or split content |
- | 🟡 MISSING | File not found or broken symlink | Check path, fix symlink target |
- | 🟢 Bootstrap <10% | Healthy | No action needed |
- | 🟠 Bootstrap >15% | Heavy | Review workspace files for bloat |
- ## Image Output (for chat / sharing)
- Generate a PNG image directly — no terminal screenshot needed:
- ```bash
- python3 scripts/context-doctor.py --png /tmp/context-doctor.png
- ```
- The script renders a colored terminal-style image via Rich SVG export.
- Requires: `rich` (pip3 install rich) + one of: `rsvg-convert` (brew install librsvg) or `cairosvg` (pip3 install cairosvg).
- **Agent workflow**: When a user asks about context health in chat, run with `--png` and send the image directly. The output path is printed to stdout on success.
README.md · README · 81 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # context-doctor 🧠
- Visualize and diagnose your OpenClaw context window usage.
- One command to see what's eating your tokens, which files are healthy, and how much room you have left for actual conversation.
- 
- ## Install
- ```bash
- clawhub install context-doctor
- ```
- Or clone this repo into your workspace skills directory:
- ```bash
- git clone https://github.com/jzOcb/context-doctor.git ~/.openclaw/workspace/skills/context-doctor
- ```
- ## Usage
- ### Terminal (colored output)
- ```bash
- python3 scripts/context-doctor.py
- ```
- ### PNG image (for chat / sharing)
- ```bash
- python3 scripts/context-doctor.py --png /tmp/context-doctor.png
- ```
- Requires: `rich` (`pip3 install rich`) + `rsvg-convert` (`brew install librsvg`) or `cairosvg` (`pip3 install cairosvg`)
- ### JSON (pipe to other tools)
- ```bash
- python3 scripts/context-doctor.py --json
- ```
- ### Options
- | Flag | Description |
- |------|-------------|
- | `--workspace PATH` | Custom workspace path (default: auto-detect) |
- | `--ctx-size N` | Context window size in tokens (default: 200000) |
- | `--png PATH` | Output as PNG image |
- | `--json` | Output structured JSON |
- | `--no-color` | Disable ANSI colors |
- ## What it shows
- ### 📁 Workspace Files
- Each bootstrap file with status, character count, and token estimate:
- - **✓ OK** — file loaded normally
- - **⚠ TRUNCATED** — file exceeds limit, instructions silently cut
- - **✗ MISSING** — file not found or broken symlink
- ### 🔧 Installed Skills
- All discovered skills from system, workspace, and global directories.
- Skills are loaded on-demand (not in bootstrap), shown for awareness.
- ### 📊 Token Budget
- How your context window is split:
- - System Prompt (framework)
- - Workspace Files
- - Skills List (metadata)
- - Tool Schemas + Summaries
- - **Free for conversation**
- ### Health Score
- | Signal | Meaning |
- |--------|---------|
- | 🟢 <10% | Healthy — plenty of room |
- | 🟡 10-15% | Moderate — consider trimming |
- | 🔴 >15% | Heavy — agent loses context early |
- ## Agent Integration
- When installed as a skill, your OpenClaw agent can automatically run context-doctor when you ask about context window health. With `--png`, the agent generates and sends the visualization directly in chat — no terminal needed.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.