Skip to content
Back to search

context-doctor

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jzocb--context-doctor/badge.svg)](/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

i

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.

  1. ---
  2. name: context-doctor
  3. description: >
  4. Visualize and diagnose OpenClaw context window usage. Generates a terminal-rendered
  5. breakdown showing workspace files (status, chars, tokens), installed skills inventory,
  6. and token budget allocation across bootstrap components. Use when: (1) user asks about
  7. context window health or token usage, (2) debugging agent quality degradation ("agent
  8. got dumber"), (3) after editing workspace files to verify impact, (4) auditing bootstrap
  9. overhead. NOT for: conversation history analysis, model selection, or cost tracking.
  10. ---
  11. # Context Doctor
  12. Diagnose and visualize how the context window budget is allocated.
  13. ## Quick Start
  14. Run the visualization script:
  15. ```bash
  16. python3 scripts/context-doctor.py
  17. ```
  18. The script auto-detects:
  19. - Workspace path (`~/.openclaw/workspace` or `OPENCLAW_WORKSPACE` env)
  20. - OpenClaw version (via `openclaw --version`)
  21. - Installed skills (system + workspace)
  22. - Bootstrap file sizes and status
  23. ## Output Sections
  24. ### 1. Workspace Files
  25. Shows each bootstrap file with:
  26. - **Status**: ✓ OK / ✗ MISSING / ⚠ TRUNCATED (symlink target missing = MISSING)
  27. - **Characters & Tokens**: Raw size and estimated token count (chars/4)
  28. - **Visual bar**: Proportional to file size
  29. ### 2. Installed Skills
  30. Lists all discovered SKILL.md files from system and workspace skill directories.
  31. Skills are loaded on-demand, not in bootstrap — shown for awareness only.
  32. ### 3. Token Budget
  33. Breaks down bootstrap overhead:
  34. - System Prompt (framework)
  35. - Workspace Files (from scan)
  36. - Skills List (metadata descriptions)
  37. - Tool Schemas + Summaries
  38. Shows total bootstrap % vs free conversation space.
  39. ## Diagnostic Signals
  40. | Signal | Meaning | Action |
  41. |--------|---------|--------|
  42. | 🔴 TRUNCATED | File exceeded max chars, silently cut | Reduce file size or split content |
  43. | 🟡 MISSING | File not found or broken symlink | Check path, fix symlink target |
  44. | 🟢 Bootstrap <10% | Healthy | No action needed |
  45. | 🟠 Bootstrap >15% | Heavy | Review workspace files for bloat |
  46. ## Image Output (for chat / sharing)
  47. Generate a PNG image directly — no terminal screenshot needed:
  48. ```bash
  49. python3 scripts/context-doctor.py --png /tmp/context-doctor.png
  50. ```
  51. The script renders a colored terminal-style image via Rich SVG export.
  52. Requires: `rich` (pip3 install rich) + one of: `rsvg-convert` (brew install librsvg) or `cairosvg` (pip3 install cairosvg).
  53. **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.

  1. # context-doctor 🧠
  2. Visualize and diagnose your OpenClaw context window usage.
  3. One command to see what's eating your tokens, which files are healthy, and how much room you have left for actual conversation.
  4. ![context-doctor output](assets/screenshot.png)
  5. ## Install
  6. ```bash
  7. clawhub install context-doctor
  8. ```
  9. Or clone this repo into your workspace skills directory:
  10. ```bash
  11. git clone https://github.com/jzOcb/context-doctor.git ~/.openclaw/workspace/skills/context-doctor
  12. ```
  13. ## Usage
  14. ### Terminal (colored output)
  15. ```bash
  16. python3 scripts/context-doctor.py
  17. ```
  18. ### PNG image (for chat / sharing)
  19. ```bash
  20. python3 scripts/context-doctor.py --png /tmp/context-doctor.png
  21. ```
  22. Requires: `rich` (`pip3 install rich`) + `rsvg-convert` (`brew install librsvg`) or `cairosvg` (`pip3 install cairosvg`)
  23. ### JSON (pipe to other tools)
  24. ```bash
  25. python3 scripts/context-doctor.py --json
  26. ```
  27. ### Options
  28. | Flag | Description |
  29. |------|-------------|
  30. | `--workspace PATH` | Custom workspace path (default: auto-detect) |
  31. | `--ctx-size N` | Context window size in tokens (default: 200000) |
  32. | `--png PATH` | Output as PNG image |
  33. | `--json` | Output structured JSON |
  34. | `--no-color` | Disable ANSI colors |
  35. ## What it shows
  36. ### 📁 Workspace Files
  37. Each bootstrap file with status, character count, and token estimate:
  38. - **✓ OK** — file loaded normally
  39. - **⚠ TRUNCATED** — file exceeds limit, instructions silently cut
  40. - **✗ MISSING** — file not found or broken symlink
  41. ### 🔧 Installed Skills
  42. All discovered skills from system, workspace, and global directories.
  43. Skills are loaded on-demand (not in bootstrap), shown for awareness.
  44. ### 📊 Token Budget
  45. How your context window is split:
  46. - System Prompt (framework)
  47. - Workspace Files
  48. - Skills List (metadata)
  49. - Tool Schemas + Summaries
  50. - **Free for conversation**
  51. ### Health Score
  52. | Signal | Meaning |
  53. |--------|---------|
  54. | 🟢 <10% | Healthy — plenty of room |
  55. | 🟡 10-15% | Moderate — consider trimming |
  56. | 🔴 >15% | Heavy — agent loses context early |
  57. ## Agent Integration
  58. 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.
  59. ## License
  60. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.