A GNOME Shell extension that displays Claude AI usage statistics and Claude Code session activity in your top bar.
- Session usage: 5-hour rolling window utilization percentage
- Weekly usage: 7-day rolling window utilization percentage
- Per-model usage: separate bars for model-scoped limits reported by the API (e.g. a weekly Fable cap)
- Time remaining: Countdown until usage resets
- Color-coded warnings: Yellow at 75%, red at 90%
- Configurable refresh interval: Set how often to poll the API (1-60 minutes)
- Last updated timestamp: Shows when usage data was last refreshed
- Live status: Current session status (Thinking, Running, Ready) shown in the dropdown menu
- Last tool: Shows most recent completed tool with duration (e.g., "Reading: file.js (0.8s)")
- Session duration: How long the current session has been active
- Recent commands: History of last 5 tools with execution times
Top bar display:
S: 45% W: 23% F: 42% 4h 32m
Model-scoped segments (like F: 42% for a Fable weekly limit) only appear when the API reports them.
Dropdown menu:
- Claude Code: Thinking
- Session: 45m
- Last: Reading file.js (0.8s)
- Recent Commands >
- Reading: config.ts (1.2s)
- Running: npm test (5.3s)
- Editing: index.js (0.3s)
- API Usage
- Session: 45% (resets in 4h 32m)
- Weekly: 23% (resets in 5d 12h)
- Fable (weekly): 42% (resets in 5d 12h)
- Last updated: 2 minutes ago
- GNOME Shell 45, 46, 47, 48, 49, or 50
- Python 3 (for Claude Code hooks)
- Claude Pro/Team subscription (for API usage stats)
- Claude Code CLI (for session tracking)
git clone https://github.com/ScriptSmith/claude-usage.git
cd claude-usage
./install.shThen either:
- Log out and log back in, OR
- Press Alt+F2, type
r, press Enter (X11 only)
Enable the extension:
gnome-extensions enable claude-usage@localOpen the extension preferences:
gnome-extensions prefs claude-usage@localYou'll need to enter:
- Session Key: The
sessionKeycookie from claude.ai - Organization ID: Your organization UUID
To find these:
- Log into claude.ai in your browser
- Open Developer Tools (F12)
- Go to Application > Cookies > claude.ai
- Copy the
sessionKeyvalue - Go to Network tab, find any request to
claude.ai/api - The organization ID is in the URL (e.g.,
/api/organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/...)
The extension tracks Claude Code sessions via hooks that write state to ~/.claude/session-state.json.
chmod +x /path/to/claude-usage/claude-session-hook.pyEdit ~/.claude/settings.json and merge in the hooks configuration:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "/path/to/claude-usage/claude-session-hook.py"
}
]
}
],
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "/path/to/claude-usage/claude-session-hook.py"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "/path/to/claude-usage/claude-session-hook.py"
}
]
}
],
"PreToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "/path/to/claude-usage/claude-session-hook.py"
}
]
}
],
"PostToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "/path/to/claude-usage/claude-session-hook.py"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "/path/to/claude-usage/claude-session-hook.py"
}
]
}
],
"SubagentStop": [
{
"hooks": [
{
"type": "command",
"command": "/path/to/claude-usage/claude-session-hook.py"
}
]
}
]
}
}Replace /path/to/claude-usage/ with the actual path where you cloned the repository.
A complete hooks configuration is also available in hooks-config.json for reference.
The extension polls the Claude API every 10 minutes to fetch usage statistics. The countdown timers update every second.
The hook script intercepts Claude Code events and writes session state to ~/.claude/session-state.json. The extension monitors this file for changes and updates the display in real-time.
Hook events captured:
| Event | Purpose |
|---|---|
| SessionStart | Mark session as active |
| SessionEnd | Mark session as ended |
| UserPromptSubmit | User sent message, Claude is thinking |
| PreToolUse | Tool is about to run |
| PostToolUse | Tool finished, record duration |
| Stop | Claude finished responding |
| SubagentStop | Subagent task completed |
The hooks are designed to be completely invisible to the Claude model:
- UserPromptSubmit/SessionStart: Produce zero stdout (these events would add output to model context)
- Other events: Output is only visible in verbose mode (Ctrl+O), never seen by the model
- Always exit with code 0 (no blocking)
This means Claude has no idea these hooks exist - your model quality is unaffected.
claude-usage/
├── extension.js # Main GNOME extension code
├── prefs.js # Extension preferences UI
├── metadata.json # Extension metadata
├── stylesheet.css # Extension styles
├── schemas/ # GSettings schemas
│ └── org.gnome.shell.extensions.claude-usage.gschema.xml
├── install.sh # Installation script
├── claude-session-hook.py # Claude Code hook script
├── hooks-config.json # Example hooks configuration
└── README.md # This file
# Check if enabled
gnome-extensions list --enabled | grep claude-usage
# Check for errors
journalctl -f -o cat /usr/bin/gnome-shell- Verify your session key and organization ID are correct
- Session keys expire - you may need to refresh from browser cookies
- Check the GNOME Shell log for HTTP errors
- Ensure the hook script is executable:
chmod +x claude-session-hook.py - Verify hooks are in
~/.claude/settings.json - Check that
~/.claude/session-state.jsonis being created/updated - Test the hook manually:
echo '{"hook_event_name":"SessionStart","session_id":"test"}' | python3 claude-session-hook.py
# Check the file exists and is readable
ls -la ~/.claude/session-state.json
cat ~/.claude/session-state.jsonTo test changes without logging out, run a nested GNOME Shell session:
dbus-run-session gnome-shell --devkit --waylandThis launches a separate Shell with your extension loaded, leaving your main session untouched.
MIT
