Context Window Tracker

Track and report OpenClaw context window usage with a detailed breakdown of what's consuming tokens. Use when: user asks about context usage, token usage, "h...

Security Scan

The skill largely does what it says (reads OpenClaw session and transcript files to compute token usage), but a prompt-injection pattern was detected in the SKILL.md and the skill reads sensitive local transcripts — review the code and metadata before installing.

Purpose & Capability

The name/description match the code and instructions: the script reads OpenClaw session store and transcript (.jsonl) files to compute token usage, breakdowns, and estimates. No unrelated cloud credentials, binaries, or external services are requested.

Instruction Scope

SKILL.md tells the agent to run the included Python script and gives rules about how to present the results (e.g., one-line summaries, never suggest deleting files). The instructions only reference OpenClaw session/transcript paths (expected). However a pre-scan detected a 'system-prompt-override' pattern in SKILL.md — the file contains directives aimed at guiding agent behaviour which could be used to influence system prompts. The directives themselves appear benign here, but flagging is warranted.

Install Mechanism

No install spec is provided (instruction-only). The skill includes a local Python script but does not download or install external packages or run remote installers, which minimizes install-time risk.

Credentials

The skill requests no environment variables or external credentials. It does read files under ~/.openclaw/agents/... (sessions.json and transcript .jsonl) — this is appropriate for a context-tracking tool, but those files contain full conversation transcripts and could include secrets or private data, so access is sensitive and should be considered before enabling the skill.

Persistence & Privilege

The skill does not request always: true and does not declare modifications to other skills or system-wide settings. It appears to run only when invoked by the user or agent (normal behaviour).

Scan Findings in Context

[system-prompt-override] unexpected: The SKILL.md contains explicit directives about agent behaviour (how to present output, what to avoid). The scanner flagged this as a 'system-prompt-override' pattern — while some guidance is normal for skills, such directives can be used to influence agent/system prompts and merit manual review.

What to consider before installing

This skill appears consistent with its purpose: it reads OpenClaw session store and transcript files (under ~/.openclaw/agents/...) and computes token usage. Before installing: 1) Review the full script (particularly the truncated end of the file) to confirm there are no network calls, telemetry, or file writes that would exfiltrate transcripts. 2) Remember transcripts contain complete conversation history (possibly secrets); only enable the skill if you trust the author and have reviewed the code. 3) The SKILL.md includes behaviour directives flagged as potential prompt-injection — they look like presentation rules but could influence agent prompts; be cautious about allowing autonomous invocation if you are unsure. If you want, provide the complete script output (untruncated) and I can re-check for network activity or hidden behavior.

Shows how much context window is left, without opening the terminal.

When to Use

• "Check my context"
• "How much context am I using?"
• "How full is my context window?"
• "Tokens remaining"
• "Am I close to the limit?"
• Any question about context usage

Two Modes

Compact (default)

One line, glanceable. Good for quick checks.

python3 scripts/context_report.py

Detailed

Full breakdown with per-file system prompt, conversation split, trends, and thinking status. Use when the user asks for specifics.

python3 scripts/context_report.py --detailed

Both modes auto-detect the most recently updated session. Options:

--session <key>    Target a specific session
--agent <name>     Target a specific agent (default: main)
--detailed         Full breakdown instead of compact one-liner

Output Format

Compact

🟢 [███░░░░░░░░░░░░░░░░░] 29.8K / 202.8K tokens (15% used) | ~736 turns left | Cache: 99%

Detailed

🟢 [███░░░░░░░░░░░░░░░░░] Context Usage: 29.8K / 202.8K (15%)

────────────────────
**Token Breakdown**
  System Prompt: ~10.2K tokens (5%)
    AGENTS.md: ~2.0K
    SOUL.md: ~416
    TOOLS.md: ~717
    MEMORY.md: ~2.3K
  📦 Framework overhead: ~5.3K (tool schemas, skill list, runtime)
  Conversation: ~19.6K tokens (10%)
  📊 Total Used: 29.8K (15%)
  Remaining: 173.0K (85%)

────────────────────
**Trends**
  Avg tokens per turn: ~1.2K tokens
  ⏳ Estimated turns remaining: ~144

────────────────────
**Session Stats**
  📥 Total input: 25K | 📤 Total output: 1.8K | Cache hit rate: 99%
  Thinking: active (3/12 responses)
────────────────────

The bar uses █ (filled) and ░ (empty) across 20 segments (each = 5%). The indicator shifts: 🟢 under 60%, 🟡 60-80%, 🔴 over 80%.

Guidance

When the user asks about context usage, you may optionally include a brief note about remaining capacity based on the script output and the current conversation. Only do this at 75%+ usage. Skip for fresh sessions.

Rules:

• One line max. Reference the actual task, not generic categories.
• Don't prescribe actions, describe what fits.
• Never suggest deleting workspace files or changing system config.

What's Exact vs Estimated

✅ Exact (from provider):
  • Total tokens used (from transcript)
  • Context window limit (from session store)
  • Cache hit rate

⚠ Estimated:
  • Per-file system prompt breakdown (chars ÷ 4)
  • Turns remaining (extrapolated from recent growth rate)
  • Thinking token count (bundled by provider, not separately reported)

Notes

• Script reads the transcript (.jsonl) as source of truth. The session store can lag behind by thousands of tokens.
• If the context window limit is unknown, the script shows tokens used without a percentage.
• See references/data-sources.md for file paths
• See references/thinking-tokens.md for how reasoning tokens affect counts