Context Doctor

Visualize and diagnose OpenClaw context window usage. Generates a terminal-rendered breakdown showing workspace files (status, chars, tokens), installed skil...

Security Scan

The skill's code, instructions, and resource access match its stated purpose (diagnosing OpenClaw context usage); it reads local workspace/skill files and runs local openclaw commands but does not attempt network exfiltration or request unrelated credentials.

Purpose & Capability

Name/description (context window diagnosis) aligns with what the code does: scans a workspace, reads bootstrap files, enumerates SKILL.md files, estimates token usage, and optionally renders a PNG. No unrelated resources (cloud credentials, unrelated OS services) are requested.

Instruction Scope

SKILL.md instructs running the included Python script which performs only local discovery and rendering. The script reads files under the workspace, inspects installed-skill directories, and calls local 'openclaw' for version/config. It does not instruct reading unrelated user files, nor does it post data to remote endpoints.

Install Mechanism

No install spec is present (instruction-only with a bundled script). Image export requires optional packages (rich and either rsvg-convert or cairosvg) as documented; these are standard local dependencies and there are no downloads from untrusted URLs.

Credentials

The skill requires no environment variables or credentials. The script optionally respects OPENCLAW_WORKSPACE and invokes 'openclaw' CLI if present — this is reasonable and proportional to discovering workspace location and version.

Persistence & Privilege

The skill does not request always:true, does not modify other skills or system configuration, and does not persist credentials. It only runs when invoked and prints/writes local output (PNG path) as instructed.

Assessment

This skill appears to do exactly what it says: it scans your OpenClaw workspace and skill directories, calls the local 'openclaw' CLI if available, and renders a local visualization. Before installing/running, consider: (1) it will read any files in your OpenClaw workspace and any SKILL.md under scanned skill dirs—avoid running it if those directories contain secrets you don't want inspected; (2) PNG export requires installing 'rich' and either 'cairosvg' or a system 'rsvg-convert' binary; (3) if you are cautious, review the bundled script and run it in a contained environment (or on a copy of the workspace) to confirm behaviour. Overall, nothing in the files indicates network exfiltration or unrelated privilege access.

Diagnose and visualize how the context window budget is allocated.

Quick Start

Run the visualization script:

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:

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.