claude-monitor

中文  |  English?

---

Claude Lens

A real-time Claude Code monitoring plugin — three-color signal light + token usage tracking, all in your status bar.

● Working         | in:12.4K out:38.2K tot:50.6K

Claude Lens integrates directly into Claude Code's native status bar. No separate terminal window, no network dependency — just a clean, compact status line that tells you what Claude is doing and how many tokens it's using right now.

Features

• Three-color signal light — Green (idle/ready), Yellow (waiting/error), Red (working/tool-running)
• Real-time token tracking — Input/output/total token counts parsed from the session transcript
• 12/12 Hook coverage — Every Claude Code lifecycle event is monitored: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, Stop, SessionEnd, and more
• Zero network — File-bridge architecture (state.json + watchfiles), everything stays local
• Native integration — Uses Claude Code's built-in statusLine feature, no external TUI process
• Fault-tolerant — JSON corruption recovery, file locking for concurrent access, graceful degradation when token data is unavailable
• Session-aware — Token counts are filtered by session_id, so you only see current-session data

Quick Start

1. Install

# Clone the repository
git clone https://github.com/Junhaozhang-127/claude-lens.git
cd claude-lens

# Install dependencies
pip install -r requirements.txt

2. Register as a Claude Code Plugin

claude plugin add /path/to/claude-lens

Or manually add the hook configuration from .claude-plugin/plugin.json to your .claude/settings.local.json.

3. Restart Claude Code

The monitor appears in the status bar automatically on your next session. Status refreshes every 2 seconds.

What You'll See

Status	Signal	Meaning
idle	🟢 Green	Ready, waiting for your prompt
working	🔴 Red	Claude is processing your request
tool_running	🔴 Red	Tools are actively executing
waiting_user	🟡 Yellow	Needs your input or confirmation
permission_denied	🟡 Yellow	You denied a permission request
recoverable_error	🟡 Yellow	A tool failed, but work continues
fatal_error	🔴 Red	Critical failure, needs attention
closing	🟢 Green	Session ending, countdown to exit

Status Bar Format

● STATUS_TEXT | in:INPUT out:OUTPUT tot:TOTAL

Example:

● Working | in:12.4K out:38.2K tot:50.6K

When token data is not yet available:

● Working | Token: --

Commands

Command	Description
/claude-monitor status	Show detailed session state (status, tokens, elapsed time)
/claude-monitor reset	Reset to default idle state (useful for debugging)

Configuration

All configurable via .claude-plugin/plugin.json or .claude/settings.local.json:

Option	Type	Default	Description
monitor_enabled	boolean	true	Enable/disable the status bar monitor
auto_close_delay	number	30	Seconds before auto-close after session end
token_source	string	"auto"	Token data source: auto, transcript, or off

Disclaimer: Token counts are parsed from the Claude Code transcript and are cumulative for the current session.

Architecture

Claude Code Process (lifecycle events)
        │
        ├─ SessionStart  ──→ launch_monitor.py  → init state.json
        ├─ UserPromptSubmit → update_state.py   → status = working
        ├─ PreToolUse ──────→ update_state.py   → tool_started++
        ├─ PostToolUse ─────→ update_state.py   → tool_finished++
        ├─ PermissionRequest → update_state.py  → status = waiting_user
        ├─ ... (12 hooks total)
        └─ SessionEnd ──────→ write_closing_state.py → status = closing
                  │
          state.json (file bridge)
                  │
        Claude Code statusLine ← status_line.py (every 2s)
                  │
        ┌──────────────────────────────┐
        │ ● Working | in:12.4K out:... │
        └──────────────────────────────┘
              Status Bar