Troubleshooting

September 2, 2026 · View on GitHub

Start here: `context-stats doctor`

Most "it doesn't work" reports come down to the status line never having been activated — pip install context-stats installs the commands but cannot wire statusLine into Claude Code's ~/.claude/settings.json for you. doctor checks that and every other link in the chain, and prints the exact fix:

context-stats doctor

# repair the settings.json wiring in place (backs up first, preserves other keys)
context-stats doctor --fix

# replace a statusLine that currently points at a different tool
context-stats doctor --fix --force

It exits non-zero when any check fails. Restart Claude Code after a --fix.

The "statusLine is not wired" startup hint

Because the CLI is the one context-stats process guaranteed to run while the status line is unwired, every context-stats invocation prints a one-line hint on stderr until statusLine is configured:

! statusLine is not wired into ~/.claude/settings.json — the status line will never run. Fix: context-stats doctor --fix

The hint is stderr-only and never changes the command's output or exit code. It appears once settings.json exists and parses but has no effective statusLine block; it stays silent when the file is missing, unreadable, or malformed (doctor diagnoses those on its own terms). Running context-stats doctor --fix wires the status line and the hint disappears.

To suppress the hint without wiring the status line:

# in ~/.claude/statusline.conf
suppress_setup_hint=true

or with the environment variable (no config file needed):

export CONTEXT_STATS_SUPPRESS_SETUP_HINT=1

Either one suppresses it; see docs/configuration.md for the full key reference.

Common Issues

Status line not appearing

Run context-stats doctor first — it covers every step below automatically.

macOS/Linux (shell installer):

Check script is executable:
```
chmod +x ~/.claude/statusline.py
```

Test the script:

echo '{"model":{"display_name":"Test"}}' | python3 ~/.claude/statusline.py

Verify settings.json configuration:
```
cat ~/.claude/settings.json
```

pip install:

Verify the command is available:
```
which claude-statusline
```

Test it:

echo '{"model":{"display_name":"Test"}}' | claude-statusline

Ensure your settings.json uses "command": "claude-statusline" (not a file path).

Windows (Python):

echo {"model":{"display_name":"Test"}} | python %USERPROFILE%\.claude\statusline.py

context-stats command not found

Verify installation:
```
which context-stats
```
Reinstall if missing:
```
pip install context-stats
```

Check PATH if pip installed to user directory:

# zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

pip install fails

Ensure Python 3.10+:
```
python3 --version
```
Try with --user flag:
```
pip install --user context-stats
```
Or use uv:
```
uv pip install context-stats
```

`error: unrecognized arguments: <session_id>` on export

Running context-stats <session_id> export fails with:

python3 -m claude_statusline.cli.context_stats: error: unrecognized arguments: <session_id>

The installed Python package is missing or too old to know the export subcommand — typically a stale global install left behind by an installer from before the package was auto-installed.

Check the installed version and upgrade it:

pip show context-stats
pip install --upgrade context-stats

If pip is unavailable in your environment, reinstall with the shell installer, which auto-installs/upgrades the matching package version:
```
curl -fsSL https://raw.githubusercontent.com/luongnv89/context-stats/main/install.sh | bash
```

Verify the fix from any directory:

context-stats --version
context-stats <session_id> export --output report.md

No token graph data

Token history requires:

Python statusline script (the Python script writes state files)
show_delta=true in ~/.claude/statusline.conf (default)
Active Claude Code session generating state files
State files at ~/.claude/statusline/statusline.<session_id>.state

Check for state files:

ls -la ~/.claude/statusline/statusline.*.state

Git info not showing

Verify you're in a git repository:
```
git rev-parse --is-inside-work-tree
```
Check git is installed:
```
which git
```
Git commands have a 5-second timeout. If your repo is very large, git operations may time out silently.

Wrong token colors

Context token colors are based on Model Intelligence (MI) score, not raw percentages:

MI Score	Expected Color
> 0.70	Green
0.40–0.70	Yellow
< 0.40	Red

Per-property colors (e.g., color_context_length=bold_white) override MI-based coloring when explicitly set. If colors look wrong, check terminal color support and your ~/.claude/statusline.conf settings.

Delta always shows zero

Token delta requires multiple statusline refreshes. The first refresh establishes a baseline; subsequent refreshes show the delta.

If delta is always zero after multiple refreshes, check that the state file is being written:

wc -l ~/.claude/statusline/statusline.*.state

Configuration not taking effect

Check config file location:
```
cat ~/.claude/statusline.conf
```

Verify syntax (no spaces around =):

# Correct
show_delta=true

# Wrong
show_delta = true

Restart Claude Code after config changes.

Debug Mode

Test script output

# Create test input
cat << 'EOF' > /tmp/test-input.json
{
  "model": {"display_name": "Opus 4.5"},
  "cwd": "/test/project",
  "session_id": "test123",
  "context": {
    "tokens_remaining": 64000,
    "context_window": 200000,
    "autocompact_buffer_tokens": 45000
  }
}
EOF

# Test installed version
cat /tmp/test-input.json | claude-statusline

# Or test standalone script directly
cat /tmp/test-input.json | python3 ~/.claude/statusline.py

Check state files

# View state file content
cat ~/.claude/statusline/statusline.*.state

# Watch state file updates
watch -n 1 'tail -5 ~/.claude/statusline/statusline.*.state'

Getting Help

Check existing issues
Open a new issue with:
- Operating system
- Shell type (bash/zsh)
- Installation method (pip, uv, manual)
- Script version being used
- Error messages or unexpected behavior