# Claude Code Goblin
Python command line tool to help with Claude Code utilities and Claude Code usage analytics and long-term tracking.
**Quick Start:** Install with `pip install claude-goblin` and use `ccg --help` for commands or `ccg usage` to start tracking. Below are some examples of outputs that this command line can give you.
> [!NOTE]
> Both `claude-goblin` and `ccg` work interchangeably as command aliases.
## Example outputs
**TUI Dashboard:**
---
**MacOS status bar for usage limits:**
---
**GitHub activity-style heatmap of annual usage:**
---
> [!NOTE]
> This tool was developed and tested on macOS (Python 3.13). Should work on Linux and Windows but is untested on those platforms.
## Features
- Local snapshotting of Claude Code logs for analytics
- Local snapshotting of usage limits from the Claude Code `/usage` command
- Dashboard and stats of usage and limit history
- Project anonymization for sharing screenshots (`--anon` flag)
- Hook setup to automate data logging or analysis of Claude Code
- Audio notifications for Claude Code completion, permission requests, and conversation compaction
- Text-to-speech (TTS) notifications with customizable hook selection (macOS only)
## Installation
### From PyPI (recommended)
```bash
# Install from PyPI
pip install claude-goblin
# Optional: Install export dependencies for PNG/SVG generation
pip install "claude-goblin[export]"
```
### From source
```bash
# Clone the repository
git clone https://github.com/data-goblin/claude-goblin.git
cd claude-goblin
# Install with pip
pip install -e .
# Optional: Install export dependencies
pip install -e ".[export]"
```
## First-Time Setup
After installation, ensure the `claude` CLI is in your PATH, then start tracking:
```bash
# Verify claude CLI is accessible
which claude
# View your current usage dashboard
ccg usage
# (Optional) Enable automatic tracking with hooks
ccg setup-hooks usage
```
**Note**: The `usage` command automatically saves your data to the historical database every time you run it. No manual setup required. If `claude` is not in your PATH, see [Troubleshooting](#troubleshooting) below.
### Commands Explained
- **`update-usage`**: Update historical database with latest data and fill in missing date gaps with empty records (use when you want continuous date coverage for the heatmap)
For most users, just run `usage` regularly and it will handle data tracking automatically. Use `setup-hooks usage` to automate this completely.
## Commands
| Command | Description |
|---------|-------------|
| **Dashboard & Analytics** | |
| `ccg usage` | Show usage dashboard with KPI cards and breakdowns |
| `ccg usage --live` | Auto-refresh dashboard every 5 seconds |
| `ccg usage --fast` | Skip live limits for faster rendering |
| `ccg usage --anon` | Anonymize project names (project-001, project-002, etc.) |
| `ccg limits` | Show current usage limits (session, week, Opus) |
| `ccg stats` | Show detailed statistics and cost analysis |
| `ccg stats --fast` | Skip live limits for faster rendering |
| `ccg status-bar [type]` | Launch macOS menu bar app (session\|weekly\|opus) |
| **Export** | |
| `ccg export` | Export yearly heatmap as PNG (default) |
| `ccg export --svg` | Export as SVG image |
| `ccg export --open` | Export and open the image |
| `ccg export -y 2024` | Export specific year |
| `ccg export -o output.png` | Specify output file path |
| **Data Management** | |
| `ccg update-usage` | Update historical database with latest data |
| `ccg delete-usage --force` | Delete historical database (requires --force) |
| `ccg restore-backup` | Restore from backup |
| **Hooks (Advanced)** | |
| `ccg setup-hooks usage` | Auto-track usage after each Claude response |
| `ccg setup-hooks audio` | Play sounds for completion, permission & compaction |
| `ccg setup-hooks audio-tts` | Speak notifications using TTS (macOS, multi-hook) |
| `ccg setup-hooks png` | Auto-generate PNG after each response |
| `ccg setup-hooks uv-standard` | Enforce uv instead of pip/pip3 |
| `ccg setup-hooks bundler-standard` | Enforce Bun instead of npm/pnpm/yarn |
| `ccg setup-hooks file-name-consistency` | Ensure consistent file naming |
| `ccg remove-hooks [type]` | Remove hooks (any hook type, or all) |
## Data Source
Claude Goblin reads usage data from Claude Code's local session logs:
```
~/.claude/projects/*.jsonl
```
**Important**: Claude Code retains session logs for approximately **30 days** (rolling window). There is no way to get other historical data without contacting Anthropic support. Claude Goblin solves this by:
- Automatically saving data to an SQLite database (`~/.claude/usage/usage_history.db`) whenever you run `--usage`
- Preserving historical data indefinitely
- Merging current + historical data for complete analytics
- Configuration to choose between saving detailed or aggregate data
## How It Works
```mermaid
graph TD
A[Claude Code] -->|writes| B[JSONL Files<br/>~/.claude/projects/*.jsonl]
A -.->|triggers| H[Hooks]
B --> ING{Ingestion<br/>--usage<br/>--update-usage}
H -.->|automates| ING
ING --> DB[(Database<br/>~/.claude/usage/usage_history.db)]
DB --> CMD1{--usage}
DB --> CMD2{--stats}
DB --> CMD3{--export}
CMD1 --> OUT1[TUI Dashboard]
CMD2 --> OUT2[Summary Stats<br/>in Terminal]
CMD3 --> OUT3[Annual Activity PNG]
H -.->|automates| CMD3
style A fill:#e0e0e0,stroke:#333,color:#000
style B fill:#ff8800,stroke:#333,color:#000
style DB fill:#4a9eff,stroke:#333,color:#fff
style OUT1 fill:#90ee90,stroke:#333,color:#000
style OUT2 fill:#90ee90,stroke:#333,color:#000
style OUT3 fill:#90ee90,stroke:#333,color:#000
style H fill:#ffeb3b,stroke:#333,color:#000
```
**Key Points:**
- **JSONL files** are raw logs with a 30-day rolling window (older data disappears)
- **Ingestion** step reads JSONL and saves to DB (with automatic deduplication via `UNIQUE` constraint)
- **Database** is the single source of truth - all display commands read from here only
- **Hooks** can automate ingestion after each Claude response
### Command Behavior
**`ccg usage`** (Display + Ingestion)
1. **Ingestion**: Reads JSONL files from `~/.claude/projects/*.jsonl` and saves to DB
2. **Display**: Reads data from DB and renders dashboard
**`ccg export`** (Display only)
1. Reads data from DB at `~/.claude/usage/usage_history.db`
2. Generates yearly heatmap
3. Exports to current directory as `claude-usage-<timestamp>.png` (or specify with `-o`)
**`ccg stats`** (Display + Ingestion)
1. **Ingestion**: Reads JSONL files from `~/.claude/projects/*.jsonl` and saves to DB
2. **Display**: Reads data from DB and displays comprehensive statistics
**`ccg update-usage`** (Ingestion only)
1. Reads JSONL files from `~/.claude/projects/*.jsonl`
2. Saves to DB at `~/.claude/usage/usage_history.db` (with automatic deduplication)
3. Fills in missing dates with empty records (ensures continuous heatmap)
### File Locations
| File | Location | Purpose |
|------|----------|---------|
| **JSONL logs** | `~/.claude/projects/*.jsonl` | Current 30-day usage data from Claude Code |
| **SQLite DB** | `~/.claude/usage/usage_history.db` | Historical usage data preserved indefinitely |
| **Default exports** | `~/.claude/usage/claude-usage-<timestamp>.png` | PNG/SVG heatmaps (default location unless `-o` is used) |
| **Hook exports** | `~/.claude/usage/claude-usage.png` | Default location for PNG hook auto-updates |
## --usage TUI dashboard
Example TUI:
## --export Heatmap
Export a GitHub-style yearly activity heatmap:
```bash
ccg export --open
```
Example heatmap:
### --export Formats
- **PNG** (default): `ccg export`
## --status-bar (macOS only)
Launch a menu bar app showing your Claude Code usage limits:
```bash
# Show weekly usage (default)
ccg status-bar weekly
# Show session usage
ccg status-bar session
# Show Opus weekly usage
ccg status-bar opus
```
The menu bar displays "CC: XX%" and clicking it shows all three limits (Session, Weekly, Opus) with reset times.
**Running in background:**
- Use `&` to run in background: `ccg status-bar weekly &`
- Use `nohup` to persist after terminal closes: `nohup ccg status-bar weekly > /dev/null 2>&1 &`
Example:
## Hooks
Claude Goblin can integrate with Claude Code's hook system to automate various tasks. Hooks trigger automatically based on Claude Code events.
### Claude Goblin Hook Types
#### Usage Hook
Automatically tracks usage data after each Claude response:
```bash
ccg setup-hooks usage
```
This adds a hook that runs `ccg update-usage --fast` after each Claude response, keeping your historical database up-to-date.
#### Audio Hook
Plays system sounds for three different events:
```bash
ccg setup-hooks audio
```
You'll be prompted to select three sounds:
1. **Completion sound**: Plays when Claude finishes responding
2. **Permission sound**: Plays when Claude requests permission
3. **Compaction sound**: Plays before conversation compaction
Supports macOS (10 built-in sounds), Windows, and Linux.
#### Audio TTS Hook (macOS only)
Speaks notifications aloud using macOS text-to-speech:
```bash
ccg setup-hooks audio-tts
```
**Multi-hook selection** - Choose which events to speak:
1. Notification only (permission requests) - **[recommended]**
2. Stop only (when Claude finishes responding)
3. PreCompact only (before conversation compaction)
4. Notification + Stop
5. Notification + PreCompact
6. Stop + PreCompact
7. All three (Notification + Stop + PreCompact)
You can also select from 7 different voices (Samantha, Alex, Daniel, Karen, Moira, Fred, Zarvox).
**Example messages:**
- Notification: Speaks the permission request message
- Stop: "Claude finished responding"
- PreCompact: "Auto compacting conversation" or "Manually compacting conversation"
#### PNG Hook
Auto-generates usage heatmap PNG after each Claude response:
```bash
ccg setup-hooks png
```
Requires export dependencies: `pip install "claude-goblin[export]"`
### Awesome-hooks (PreToolUse)
Claude Goblin includes PreToolUse hooks from [awesome-hooks](https://github.com/boxabirds/awesome-hooks) by [@boxabirds](https://github.com/boxabirds), plus a custom Python/uv enforcement hook. These hooks intercept and validate commands before they execute.
#### uv-standard Hook
Enforces uv usage instead of pip/pip3:
```bash
ccg setup-hooks uv-standard
```
**What it does:**
- Intercepts pip/pip3 commands in Bash
- Blocks them and suggests uv equivalents
- Ensures you use uv for Python package management
**Requirements:** uv package installer ([installation](https://github.com/astral-sh/uv))
#### bundler-standard Hook
Enforces Bun usage instead of npm/pnpm/yarn:
```bash
ccg setup-hooks bundler-standard
```
**What it does:**
- Intercepts npm/pnpm/yarn commands in Bash
- Blocks them and suggests Bun equivalents
- Ensures you use Bun for JavaScript package management
**Requirements:** Bun runtime ([installation](https://bun.sh))
#### file-name-consistency Hook
Ensures consistent file naming conventions:
```bash
ccg setup-hooks file-name-consistency
```
**What it does:**
- Analyzes your project's file naming patterns using AI
- Blocks files with inconsistent naming
- Suggests correctly formatted filenames
**Requirements:** GEMINI_API_KEY environment variable ([get your key](https://aistudio.google.com/apikey))
Set the API key in your shell profile:
```bash
export GEMINI_API_KEY="your-api-key-here"
```
### Removing Hooks
```bash
# Remove specific hook type
ccg remove-hooks usage
ccg remove-hooks audio
ccg remove-hooks audio-tts
ccg remove-hooks png
ccg remove-hooks uv-standard
ccg remove-hooks bundler-standard
ccg remove-hooks file-name-consistency
# Remove all Claude Goblin hooks
ccg remove-hooks
```
## Project Anonymization
The `--anon` flag anonymizes project names when displaying usage data, perfect for sharing screenshots:
```bash
ccg usage --anon
ccg stats --anon
```
Projects are renamed to `project-001`, `project-002`, etc., ranked by total token usage (project-001 has the highest usage).
## Historical Data
Claude Goblin automatically saves data every time you run `usage`. To manually manage:
```bash
# View historical stats
ccg stats
# Update database with latest data and fill date gaps
ccg update-usage
# Delete all history
ccg delete-usage -f
```
## What It Tracks
- **Tokens**: Input, output, cache creation, cache read (by model and project)
- **Prompts**: User prompts and assistant responses
- **Sessions**: Unique conversation threads
- **Models**: Which Claude models you've used (Sonnet, Opus, Haiku)
- **Projects**: Folders/directories where you've used Claude
- **Time**: Daily activity patterns throughout the year
- **Usage Limits**: Real-time session, weekly, and Opus limits
It will also compute how much you would have had to pay if you used API pricing instead of a $200 Max plan.
## Technical Details
### Timezone Handling
All timestamps in Claude Code's JSONL files seem to be stored in **UTC**. Claude Goblin should convert to your **local timezone** when grouping activity by date. This has only been tested with European CET.
### Cache Efficiency
The token breakdown shows cache efficiency. High "Cache Read" percentages (80-90%+) mean Claude Code is effectively reusing context, which:
- Speeds up responses
- Can reduce costs on usage-based plans
- Indicates good context management
## Requirements
- Python >= 3.10
- Claude Code (for generating usage data)
- Rich >= 13.7.0 (terminal UI)
- rumps >= 0.4.0 (macOS menu bar app, macOS only)
- Pillow + CairoSVG (optional, for PNG/SVG export)
## License
MIT License - see LICENSE file for details
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request
I don't have much time but I'll review PRs when I can.
## Troubleshooting
### "No Claude Code data found"
- Ensure Claude Code is installed and you've used it at least once
- Check that `~/.claude/projects/` exists and contains `.jsonl` files
### "Claude Code CLI not found in PATH"
If you see this error, the `claude` command is not accessible. To fix:
```bash
# Check if claude is installed
which claude
# If not found, add to PATH (adjust path based on your installation)
# For zsh (default on macOS):
echo 'export PATH="$HOME/Library/Application Support/Claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# For bash:
echo 'export PATH="$HOME/Library/Application Support/Claude/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Verify it works
claude --version
```
**Note:** Token tracking will continue to work even if `claude` CLI is not found; only limits tracking requires it.
### Limits showing "Could not parse usage data"
- Run `claude` in a trusted folder first
- Claude needs folder trust to display usage limits
### Export fails
- Install export dependencies: `pip install -e ".[export]"`
- For PNG: requires Pillow and CairoSVG
### Database errors
- Try deleting and recreating: `ccg delete-usage --force`
- Then run: `ccg usage` to rebuild from current data
## **AI Tools Disclaimer**:
This project was developed with assistance from Claude Code.
## Credits
Built with:
- [Rich](https://github.com/Textualize/rich) - Terminal UI framework
- [Pillow](https://python-pillow.org/) - Image processing (optional)
- [CairoSVG](https://cairosvg.org/) - SVG to PNG conversion (optional)
Includes hooks from:
- [awesome-hooks](https://github.com/boxabirds/awesome-hooks) by [@boxabirds](https://github.com/boxabirds) - PreToolUse hooks for enforcing development standards
See [docs/attributions.md](docs/attributions.md) for full attribution details.
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-goblin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "analytics, claude, claude-code, dashboard, tui, usage, visualization",
"author": "Kurt Buhler",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ce/74/ea862704f0e9afb9541fde5eaa4a96396b31a7085efe13552dc762121be8/claude_goblin-0.1.9.tar.gz",
"platform": null,
"description": "# Claude Code Goblin\n\n\n\n\n\n\nPython command line tool to help with Claude Code utilities and Claude Code usage analytics and long-term tracking.\n\n\n**Quick Start:** Install with `pip install claude-goblin` and use `ccg --help` for commands or `ccg usage` to start tracking. Below are some examples of outputs that this command line can give you.\n\n> [!NOTE]\n> Both `claude-goblin` and `ccg` work interchangeably as command aliases.\n\n## Example outputs\n\n**TUI Dashboard:**\n\n\n\n---\n\n**MacOS status bar for usage limits:**\n\n\n\n---\n\n**GitHub activity-style heatmap of annual usage:**\n\n\n\n--- \n\n\n> [!NOTE] \n> This tool was developed and tested on macOS (Python 3.13). Should work on Linux and Windows but is untested on those platforms.\n\n\n\n## Features\n\n- Local snapshotting of Claude Code logs for analytics\n- Local snapshotting of usage limits from the Claude Code `/usage` command\n- Dashboard and stats of usage and limit history\n- Project anonymization for sharing screenshots (`--anon` flag)\n- Hook setup to automate data logging or analysis of Claude Code\n- Audio notifications for Claude Code completion, permission requests, and conversation compaction\n- Text-to-speech (TTS) notifications with customizable hook selection (macOS only)\n\n## Installation\n\n### From PyPI (recommended)\n```bash\n# Install from PyPI\npip install claude-goblin\n\n# Optional: Install export dependencies for PNG/SVG generation\npip install \"claude-goblin[export]\"\n```\n\n### From source\n```bash\n# Clone the repository\ngit clone https://github.com/data-goblin/claude-goblin.git\ncd claude-goblin\n\n# Install with pip\npip install -e .\n\n# Optional: Install export dependencies\npip install -e \".[export]\"\n```\n\n## First-Time Setup\n\nAfter installation, ensure the `claude` CLI is in your PATH, then start tracking:\n\n```bash\n# Verify claude CLI is accessible\nwhich claude\n\n# View your current usage dashboard\nccg usage\n\n# (Optional) Enable automatic tracking with hooks\nccg setup-hooks usage\n```\n\n**Note**: The `usage` command automatically saves your data to the historical database every time you run it. No manual setup required. If `claude` is not in your PATH, see [Troubleshooting](#troubleshooting) below.\n\n### Commands Explained\n\n- **`update-usage`**: Update historical database with latest data and fill in missing date gaps with empty records (use when you want continuous date coverage for the heatmap)\n\nFor most users, just run `usage` regularly and it will handle data tracking automatically. Use `setup-hooks usage` to automate this completely.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| **Dashboard & Analytics** | |\n| `ccg usage` | Show usage dashboard with KPI cards and breakdowns |\n| `ccg usage --live` | Auto-refresh dashboard every 5 seconds |\n| `ccg usage --fast` | Skip live limits for faster rendering |\n| `ccg usage --anon` | Anonymize project names (project-001, project-002, etc.) |\n| `ccg limits` | Show current usage limits (session, week, Opus) |\n| `ccg stats` | Show detailed statistics and cost analysis |\n| `ccg stats --fast` | Skip live limits for faster rendering |\n| `ccg status-bar [type]` | Launch macOS menu bar app (session\\|weekly\\|opus) |\n| **Export** | |\n| `ccg export` | Export yearly heatmap as PNG (default) |\n| `ccg export --svg` | Export as SVG image |\n| `ccg export --open` | Export and open the image |\n| `ccg export -y 2024` | Export specific year |\n| `ccg export -o output.png` | Specify output file path |\n| **Data Management** | |\n| `ccg update-usage` | Update historical database with latest data |\n| `ccg delete-usage --force` | Delete historical database (requires --force) |\n| `ccg restore-backup` | Restore from backup |\n| **Hooks (Advanced)** | |\n| `ccg setup-hooks usage` | Auto-track usage after each Claude response |\n| `ccg setup-hooks audio` | Play sounds for completion, permission & compaction |\n| `ccg setup-hooks audio-tts` | Speak notifications using TTS (macOS, multi-hook) |\n| `ccg setup-hooks png` | Auto-generate PNG after each response |\n| `ccg setup-hooks uv-standard` | Enforce uv instead of pip/pip3 |\n| `ccg setup-hooks bundler-standard` | Enforce Bun instead of npm/pnpm/yarn |\n| `ccg setup-hooks file-name-consistency` | Ensure consistent file naming |\n| `ccg remove-hooks [type]` | Remove hooks (any hook type, or all) |\n\n## Data Source\n\nClaude Goblin reads usage data from Claude Code's local session logs:\n```\n~/.claude/projects/*.jsonl\n```\n\n**Important**: Claude Code retains session logs for approximately **30 days** (rolling window). There is no way to get other historical data without contacting Anthropic support. Claude Goblin solves this by:\n- Automatically saving data to an SQLite database (`~/.claude/usage/usage_history.db`) whenever you run `--usage`\n- Preserving historical data indefinitely\n- Merging current + historical data for complete analytics\n- Configuration to choose between saving detailed or aggregate data\n\n## How It Works\n\n```mermaid\ngraph TD\n A[Claude Code] -->|writes| B[JSONL Files<br/>~/.claude/projects/*.jsonl]\n A -.->|triggers| H[Hooks]\n\n B --> ING{Ingestion<br/>--usage<br/>--update-usage}\n H -.->|automates| ING\n\n ING --> DB[(Database<br/>~/.claude/usage/usage_history.db)]\n\n DB --> CMD1{--usage}\n DB --> CMD2{--stats}\n DB --> CMD3{--export}\n\n CMD1 --> OUT1[TUI Dashboard]\n CMD2 --> OUT2[Summary Stats<br/>in Terminal]\n CMD3 --> OUT3[Annual Activity PNG]\n\n H -.->|automates| CMD3\n\n style A fill:#e0e0e0,stroke:#333,color:#000\n style B fill:#ff8800,stroke:#333,color:#000\n style DB fill:#4a9eff,stroke:#333,color:#fff\n style OUT1 fill:#90ee90,stroke:#333,color:#000\n style OUT2 fill:#90ee90,stroke:#333,color:#000\n style OUT3 fill:#90ee90,stroke:#333,color:#000\n style H fill:#ffeb3b,stroke:#333,color:#000\n```\n\n**Key Points:**\n- **JSONL files** are raw logs with a 30-day rolling window (older data disappears)\n- **Ingestion** step reads JSONL and saves to DB (with automatic deduplication via `UNIQUE` constraint)\n- **Database** is the single source of truth - all display commands read from here only\n- **Hooks** can automate ingestion after each Claude response\n\n### Command Behavior\n\n**`ccg usage`** (Display + Ingestion)\n1. **Ingestion**: Reads JSONL files from `~/.claude/projects/*.jsonl` and saves to DB\n2. **Display**: Reads data from DB and renders dashboard\n\n**`ccg export`** (Display only)\n1. Reads data from DB at `~/.claude/usage/usage_history.db`\n2. Generates yearly heatmap\n3. Exports to current directory as `claude-usage-<timestamp>.png` (or specify with `-o`)\n\n**`ccg stats`** (Display + Ingestion)\n1. **Ingestion**: Reads JSONL files from `~/.claude/projects/*.jsonl` and saves to DB\n2. **Display**: Reads data from DB and displays comprehensive statistics\n\n**`ccg update-usage`** (Ingestion only)\n1. Reads JSONL files from `~/.claude/projects/*.jsonl`\n2. Saves to DB at `~/.claude/usage/usage_history.db` (with automatic deduplication)\n3. Fills in missing dates with empty records (ensures continuous heatmap)\n\n### File Locations\n\n| File | Location | Purpose |\n|------|----------|---------|\n| **JSONL logs** | `~/.claude/projects/*.jsonl` | Current 30-day usage data from Claude Code |\n| **SQLite DB** | `~/.claude/usage/usage_history.db` | Historical usage data preserved indefinitely |\n| **Default exports** | `~/.claude/usage/claude-usage-<timestamp>.png` | PNG/SVG heatmaps (default location unless `-o` is used) |\n| **Hook exports** | `~/.claude/usage/claude-usage.png` | Default location for PNG hook auto-updates |\n\n## --usage TUI dashboard\n\nExample TUI:\n\n\n\n## --export Heatmap\n\nExport a GitHub-style yearly activity heatmap:\n\n```bash\nccg export --open\n```\n\nExample heatmap:\n\n\n\n### --export Formats\n\n- **PNG** (default): `ccg export`\n\n## --status-bar (macOS only)\n\nLaunch a menu bar app showing your Claude Code usage limits:\n\n```bash\n# Show weekly usage (default)\nccg status-bar weekly\n\n# Show session usage\nccg status-bar session\n\n# Show Opus weekly usage\nccg status-bar opus\n```\n\nThe menu bar displays \"CC: XX%\" and clicking it shows all three limits (Session, Weekly, Opus) with reset times.\n\n**Running in background:**\n- Use `&` to run in background: `ccg status-bar weekly &`\n- Use `nohup` to persist after terminal closes: `nohup ccg status-bar weekly > /dev/null 2>&1 &`\n\nExample:\n\n\n\n## Hooks\n\nClaude Goblin can integrate with Claude Code's hook system to automate various tasks. Hooks trigger automatically based on Claude Code events.\n\n### Claude Goblin Hook Types\n\n#### Usage Hook\nAutomatically tracks usage data after each Claude response:\n```bash\nccg setup-hooks usage\n```\n\nThis adds a hook that runs `ccg update-usage --fast` after each Claude response, keeping your historical database up-to-date.\n\n#### Audio Hook\nPlays system sounds for three different events:\n```bash\nccg setup-hooks audio\n```\n\nYou'll be prompted to select three sounds:\n1. **Completion sound**: Plays when Claude finishes responding\n2. **Permission sound**: Plays when Claude requests permission\n3. **Compaction sound**: Plays before conversation compaction\n\nSupports macOS (10 built-in sounds), Windows, and Linux.\n\n#### Audio TTS Hook (macOS only)\nSpeaks notifications aloud using macOS text-to-speech:\n```bash\nccg setup-hooks audio-tts\n```\n\n**Multi-hook selection** - Choose which events to speak:\n1. Notification only (permission requests) - **[recommended]**\n2. Stop only (when Claude finishes responding)\n3. PreCompact only (before conversation compaction)\n4. Notification + Stop\n5. Notification + PreCompact\n6. Stop + PreCompact\n7. All three (Notification + Stop + PreCompact)\n\nYou can also select from 7 different voices (Samantha, Alex, Daniel, Karen, Moira, Fred, Zarvox).\n\n**Example messages:**\n- Notification: Speaks the permission request message\n- Stop: \"Claude finished responding\"\n- PreCompact: \"Auto compacting conversation\" or \"Manually compacting conversation\"\n\n#### PNG Hook\nAuto-generates usage heatmap PNG after each Claude response:\n```bash\nccg setup-hooks png\n```\n\nRequires export dependencies: `pip install \"claude-goblin[export]\"`\n\n### Awesome-hooks (PreToolUse)\n\nClaude Goblin includes PreToolUse hooks from [awesome-hooks](https://github.com/boxabirds/awesome-hooks) by [@boxabirds](https://github.com/boxabirds), plus a custom Python/uv enforcement hook. These hooks intercept and validate commands before they execute.\n\n#### uv-standard Hook\nEnforces uv usage instead of pip/pip3:\n```bash\nccg setup-hooks uv-standard\n```\n\n**What it does:**\n- Intercepts pip/pip3 commands in Bash\n- Blocks them and suggests uv equivalents\n- Ensures you use uv for Python package management\n\n**Requirements:** uv package installer ([installation](https://github.com/astral-sh/uv))\n\n#### bundler-standard Hook\nEnforces Bun usage instead of npm/pnpm/yarn:\n```bash\nccg setup-hooks bundler-standard\n```\n\n**What it does:**\n- Intercepts npm/pnpm/yarn commands in Bash\n- Blocks them and suggests Bun equivalents\n- Ensures you use Bun for JavaScript package management\n\n**Requirements:** Bun runtime ([installation](https://bun.sh))\n\n#### file-name-consistency Hook\nEnsures consistent file naming conventions:\n```bash\nccg setup-hooks file-name-consistency\n```\n\n**What it does:**\n- Analyzes your project's file naming patterns using AI\n- Blocks files with inconsistent naming\n- Suggests correctly formatted filenames\n\n**Requirements:** GEMINI_API_KEY environment variable ([get your key](https://aistudio.google.com/apikey))\n\nSet the API key in your shell profile:\n```bash\nexport GEMINI_API_KEY=\"your-api-key-here\"\n```\n\n### Removing Hooks\n\n```bash\n# Remove specific hook type\nccg remove-hooks usage\nccg remove-hooks audio\nccg remove-hooks audio-tts\nccg remove-hooks png\nccg remove-hooks uv-standard\nccg remove-hooks bundler-standard\nccg remove-hooks file-name-consistency\n\n# Remove all Claude Goblin hooks\nccg remove-hooks\n```\n\n## Project Anonymization\n\nThe `--anon` flag anonymizes project names when displaying usage data, perfect for sharing screenshots:\n\n```bash\nccg usage --anon\nccg stats --anon\n```\n\nProjects are renamed to `project-001`, `project-002`, etc., ranked by total token usage (project-001 has the highest usage).\n\n## Historical Data\n\nClaude Goblin automatically saves data every time you run `usage`. To manually manage:\n\n```bash\n# View historical stats\nccg stats\n\n# Update database with latest data and fill date gaps\nccg update-usage\n\n# Delete all history\nccg delete-usage -f\n```\n\n## What It Tracks\n\n- **Tokens**: Input, output, cache creation, cache read (by model and project)\n- **Prompts**: User prompts and assistant responses\n- **Sessions**: Unique conversation threads\n- **Models**: Which Claude models you've used (Sonnet, Opus, Haiku)\n- **Projects**: Folders/directories where you've used Claude\n- **Time**: Daily activity patterns throughout the year\n- **Usage Limits**: Real-time session, weekly, and Opus limits\n\nIt will also compute how much you would have had to pay if you used API pricing instead of a $200 Max plan.\n\n\n## Technical Details\n\n### Timezone Handling\n\nAll timestamps in Claude Code's JSONL files seem to be stored in **UTC**. Claude Goblin should convert to your **local timezone** when grouping activity by date. This has only been tested with European CET.\n\n### Cache Efficiency\n\nThe token breakdown shows cache efficiency. High \"Cache Read\" percentages (80-90%+) mean Claude Code is effectively reusing context, which:\n- Speeds up responses\n- Can reduce costs on usage-based plans\n- Indicates good context management\n\n## Requirements\n\n- Python >= 3.10\n- Claude Code (for generating usage data)\n- Rich >= 13.7.0 (terminal UI)\n- rumps >= 0.4.0 (macOS menu bar app, macOS only)\n- Pillow + CairoSVG (optional, for PNG/SVG export)\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Contributing\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request\n\nI don't have much time but I'll review PRs when I can.\n\n## Troubleshooting\n\n### \"No Claude Code data found\"\n- Ensure Claude Code is installed and you've used it at least once\n- Check that `~/.claude/projects/` exists and contains `.jsonl` files\n\n### \"Claude Code CLI not found in PATH\"\nIf you see this error, the `claude` command is not accessible. To fix:\n\n```bash\n# Check if claude is installed\nwhich claude\n\n# If not found, add to PATH (adjust path based on your installation)\n# For zsh (default on macOS):\necho 'export PATH=\"$HOME/Library/Application Support/Claude/bin:$PATH\"' >> ~/.zshrc\nsource ~/.zshrc\n\n# For bash:\necho 'export PATH=\"$HOME/Library/Application Support/Claude/bin:$PATH\"' >> ~/.bashrc\nsource ~/.bashrc\n\n# Verify it works\nclaude --version\n```\n\n**Note:** Token tracking will continue to work even if `claude` CLI is not found; only limits tracking requires it.\n\n### Limits showing \"Could not parse usage data\"\n- Run `claude` in a trusted folder first\n- Claude needs folder trust to display usage limits\n\n### Export fails\n- Install export dependencies: `pip install -e \".[export]\"`\n- For PNG: requires Pillow and CairoSVG\n\n### Database errors\n- Try deleting and recreating: `ccg delete-usage --force`\n- Then run: `ccg usage` to rebuild from current data\n\n## **AI Tools Disclaimer**: \nThis project was developed with assistance from Claude Code.\n\n## Credits\n\nBuilt with:\n- [Rich](https://github.com/Textualize/rich) - Terminal UI framework\n- [Pillow](https://python-pillow.org/) - Image processing (optional)\n- [CairoSVG](https://cairosvg.org/) - SVG to PNG conversion (optional)\n\nIncludes hooks from:\n- [awesome-hooks](https://github.com/boxabirds/awesome-hooks) by [@boxabirds](https://github.com/boxabirds) - PreToolUse hooks for enforcing development standards\n\nSee [docs/attributions.md](docs/attributions.md) for full attribution details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python CLI for Claude Code utilities and usage tracking/analytics",
"version": "0.1.9",
"project_urls": {
"Homepage": "https://github.com/data-goblin/claude-goblin",
"Issues": "https://github.com/data-goblin/claude-goblin/issues",
"Repository": "https://github.com/data-goblin/claude-goblin"
},
"split_keywords": [
"analytics",
" claude",
" claude-code",
" dashboard",
" tui",
" usage",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c51e39946524908ec832c12e9449785d017b80253e2ed99c16fb8f8ff5151c3b",
"md5": "8b9fb8d72bd49e205197c026faf9a43d",
"sha256": "9be8272c2c35c15586b1f1f917b409cce32b180a3c08a849f9263eb2790aafcd"
},
"downloads": -1,
"filename": "claude_goblin-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b9fb8d72bd49e205197c026faf9a43d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 87166,
"upload_time": "2025-10-20T18:56:58",
"upload_time_iso_8601": "2025-10-20T18:56:58.896999Z",
"url": "https://files.pythonhosted.org/packages/c5/1e/39946524908ec832c12e9449785d017b80253e2ed99c16fb8f8ff5151c3b/claude_goblin-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ce74ea862704f0e9afb9541fde5eaa4a96396b31a7085efe13552dc762121be8",
"md5": "522001ab8837737689adde3fcefd99c6",
"sha256": "b3f9b6dde9541b54d4db723098c7958d6cec2451167b77a1bdae8f00835eeb23"
},
"downloads": -1,
"filename": "claude_goblin-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "522001ab8837737689adde3fcefd99c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 976879,
"upload_time": "2025-10-20T18:57:00",
"upload_time_iso_8601": "2025-10-20T18:57:00.509398Z",
"url": "https://files.pythonhosted.org/packages/ce/74/ea862704f0e9afb9541fde5eaa4a96396b31a7085efe13552dc762121be8/claude_goblin-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 18:57:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "data-goblin",
"github_project": "claude-goblin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "claude-goblin"
}
JSON
