{"id":33116652,"url":"https://github.com/PiXeL16/claudecode-macmenu","last_synced_at":"2025-11-19T20:01:27.854Z","repository":{"id":322712203,"uuid":"1090595948","full_name":"PiXeL16/claudecode-macmenu","owner":"PiXeL16","description":"A Mac Menu for Claude Code that notifies when Claude is done and shows insights","archived":false,"fork":false,"pushed_at":"2025-11-05T23:24:14.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T00:19:23.113Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PiXeL16.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-05T22:00:59.000Z","updated_at":"2025-11-05T23:24:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/PiXeL16/claudecode-macmenu","commit_stats":null,"previous_names":["pixel16/claudecode-macmenu"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/PiXeL16/claudecode-macmenu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiXeL16%2Fclaudecode-macmenu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiXeL16%2Fclaudecode-macmenu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiXeL16%2Fclaudecode-macmenu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiXeL16%2Fclaudecode-macmenu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PiXeL16","download_url":"https://codeload.github.com/PiXeL16/claudecode-macmenu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiXeL16%2Fclaudecode-macmenu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285319005,"owners_count":27151474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-19T02:00:05.673Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-11-15T03:00:22.211Z","updated_at":"2025-11-19T20:01:27.842Z","avatar_url":"https://github.com/PiXeL16.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/clauwd.png\" alt=\"Claude Code Menu Icon\" width=\"200\"/\u003e\n\n# Claude Code Mac Menu\n\n**A macOS menu bar application that enhances Claude Code with comprehensive usage analytics and real-time notifications**\n\n[Download Latest Release](https://github.com/PiXeL16/claudecode-macmenu/releases/latest) • [View Documentation](./docs/INSTALL.md) • [Report Issues](https://github.com/PiXeL16/claudecode-macmenu/issues)\n\n\u003c/div\u003e\n\n## Screenshots\n\n\u003cdiv align=\"center\"\u003e\n\n### Analytics Dashboard\n\u003cimg src=\"assets/screenshot2.png\" alt=\"Analytics Dashboard\" width=\"800\"/\u003e\n\n*Comprehensive analytics with 8 interactive charts showing usage patterns, costs, and trends*\n\n### Menu Bar Stats\n\u003cimg src=\"assets/screenshot.png\" alt=\"Menu Bar\" width=\"400\"/\u003e\n\n*Quick access to live statistics from the menu bar*\n\n### Notifications\n\u003cimg src=\"assets/screenshot3.png\" alt=\"Notification Example\" width=\"400\"/\u003e\n\n*Real-time notifications when Claude finishes tasks*\n\n\u003c/div\u003e\n\n## Features\n\n- **Comprehensive Analytics Dashboard**: Interactive charts and visualizations (Press `Cmd+A`)\n  - Daily token usage and cost trends\n  - Project-level cost breakdown\n  - Model distribution and usage patterns\n  - Hourly and weekly usage analysis\n  - Cache hit rate and savings tracking\n  - Session duration analytics\n- **Real-Time Notifications**: Hook-based notifications using Claude Code events\n  - Instant alerts when Claude finishes responding (Stop event)\n  - Task agent completion notifications (SubagentStop event)\n  - Tool-specific completion alerts (Bash, Task, etc.)\n  - Event-driven, no polling required\n- **Live Menu Bar Stats**: Quick access to key metrics\n  - Token consumption (input, output, cache tokens)\n  - Cost tracking with model-specific pricing\n  - Burn rate (tokens/min, $/hour)\n  - Session tracking (5-hour blocks)\n  - Model usage breakdown\n- **Cost Monitoring**: Track daily and total spending across all projects\n- **Customizable Settings**: Dark terminal-style UI with preferences\n- **Native macOS**: Lightweight menu bar app with Clauwd branding\n\n## Analytics Tracked\n\n**Messages**\n- Today's message count\n- Total messages\n- New message detection for notifications\n\n**Tokens**\n- Daily and total token consumption\n- Current session tokens\n- Input/output/cache token breakdown\n- Per-model token usage\n\n**Costs**\n- Daily costs\n- Total costs\n- Current session costs\n- Real-time burn rate\n\n**Sessions**\n- 5-hour session blocks\n- Daily and total session counts\n- Active session monitoring\n\n## Installation\n\n### Option 1: Download from GitHub (Recommended)\n\n1. Download the latest `Claude-Code-Menu-{version}-arm64.dmg` from [Releases](https://github.com/PiXeL16/claudecode-macmenu/releases/latest)\n2. Open the DMG file\n3. Drag \"Claude Code Menu\" to your Applications folder\n4. **Important: Remove quarantine attribute** (app is not code signed):\n   ```bash\n   xattr -cr \"/Applications/Claude Code Menu.app\"\n   ```\n5. Launch from Applications or Spotlight\n6. On first launch:\n   - Allow the app to send notifications when prompted\n   - The app will prompt you to install Claude Code hooks\n\n### Option 2: Via Homebrew (Coming Soon)\n\n```bash\nbrew install --cask claudecode-macmenu\n```\n\n*Note: Homebrew cask formula is pending approval*\n\n## Development\n\n```bash\n# Install dependencies\nmake install\n\n# Run in development mode\nmake dev\n\n# Build TypeScript\nmake build\n\n# Package for distribution\nmake package\n\n# Run tests\nmake test\n```\n\n## Release Process\n\n### For Maintainers\n\n**Quick releases:**\n```bash\n# Patch release (0.1.0 → 0.1.1)\nmake release-patch\n\n# Minor release (0.1.0 → 0.2.0)\nmake release-minor\n```\n\n**Manual version:**\n```bash\n# Specify exact version\nmake release VERSION=1.0.0\n```\n\n**What happens during release:**\n1. ✅ Updates version in `package.json`\n2. ✅ Builds the application\n3. ✅ Packages DMG and ZIP files\n4. ✅ Creates git commit and tag\n5. ✅ Pushes to GitHub\n6. ✅ GitHub Actions creates release with artifacts\n7. ✅ Update Homebrew cask manually or via PR\n\n**GitHub Actions:**\n- Automatically builds and creates releases when version tags are pushed\n- Uploads DMG and ZIP to GitHub Releases\n- Generates release notes automatically\n\n**Homebrew Submission:**\n\nTo submit to Homebrew Cask:\n1. Fork [Homebrew/homebrew-cask](https://github.com/Homebrew/homebrew-cask)\n2. Create a new branch: `git checkout -b claudecode-macmenu`\n3. Add the cask file from `homebrew/claudecode-macmenu.rb` to `Casks/c/claudecode-macmenu.rb`\n4. Test the cask:\n   ```bash\n   brew audit --new --cask claudecode-macmenu\n   brew style --fix claudecode-macmenu\n   brew install --cask claudecode-macmenu\n   brew uninstall --cask claudecode-macmenu\n   ```\n5. Commit with message: `claudecode-macmenu 0.2.0 (new cask)`\n6. Push and open a PR to `Homebrew/homebrew-cask`\n\nSee [Homebrew docs](https://docs.brew.sh/Adding-Software-to-Homebrew) for details.\n\n## Requirements\n\n- macOS 10.13 or later\n- Node.js 18 or later\n\n## Quick Start\n\n### For End Users\n\n1. **Download** the latest release `.dmg` file\n2. **Install** the app by dragging it to Applications\n3. **Launch** the app - look for the icon in your menu bar\n4. **Setup hooks** - The app will prompt you to install Claude Code hooks automatically\n   - Click \"Install Hooks\" when prompted\n   - Or go to Setup → Install Hooks from the menu\n\nThat's it! You'll now get real-time notifications when Claude Code completes tasks.\n\n📖 **Detailed installation guide:** [INSTALL.md](./docs/INSTALL.md)\n\n### For Developers\n\n```bash\n# Clone and install\ngit clone https://github.com/PiXeL16/claudecode-macmenu.git\ncd claudecode-macmenu\nnpm install\n\n# Build and run\nnpm run build\nnpm run dev\n\n# The app will prompt you to install hooks automatically\n```\n\n## Usage\n\n### Analytics Dashboard (Cmd+A)\n\nThe comprehensive analytics dashboard provides deep insights into your Claude Code usage:\n\n**Interactive Charts:**\n- **Daily Token Usage**: Line chart showing token consumption over time\n- **Cost by Project**: Bar chart of spending across different projects\n- **Model Distribution**: Pie chart showing which models you use most\n- **Cumulative Spending**: Area chart tracking total costs over time\n- **Token Type Breakdown**: Pie chart of input/output/cache token distribution\n- **Usage by Hour**: Bar chart showing when you're most active\n- **Usage by Day**: Dual-axis chart of sessions and costs by weekday\n- **Messages Per Day**: Line chart of daily message volume\n\n**Summary Cards:**\n- Cache hit rate and total savings\n- Average and longest session durations\n- Total sessions and productivity metrics\n\n**Time Range Filters:** 7 days, 30 days, 90 days, or all time\n\n### Menu Bar Features\n\nClick the Clauwd menu bar icon to access:\n\n**Live Statistics:**\n- Messages (today and total)\n- Tokens (today, total, and current session)\n- Costs (daily, total, and session)\n- Burn Rate (tokens/min, $/hour in real-time)\n- Sessions (5-hour blocks, daily count)\n- Model Breakdown (submenu with per-model stats)\n\n**Quick Actions:**\n- Analytics Dashboard (Cmd+A)\n- Refresh Stats\n- Preferences (Cmd+,)\n  - Notification settings\n  - Menu visibility options\n  - Compact mode toggle\n  - Auto-start configuration\n- Quit\n\n## Troubleshooting\n\n### \"App is damaged and can't be opened\"\n\nThis error occurs because the app is not code signed. To fix it:\n\n```bash\n# Remove the quarantine attribute\nxattr -cr \"/Applications/Claude Code Menu.app\"\n```\n\n**Why this happens:** macOS Gatekeeper marks downloaded apps as quarantined. Since the app isn't signed with an Apple Developer certificate, macOS blocks it. The `xattr` command removes this quarantine flag.\n\n**Alternative method:**\n1. Right-click the app in Finder\n2. Select \"Open\" (not double-click)\n3. Click \"Open\" in the security dialog\n\n### Future Plans\n\nCode signing requires an Apple Developer account ($99/year). Once implemented, this workaround won't be necessary.\n\n## How It Works\n\n**Notifications (Hook-Based):**\n- The app runs an HTTP server on `localhost:3456`\n- Claude Code hooks send events to the server when tasks complete\n- You get instant notifications without any polling or file watching\n- See [HOOKS.md](./docs/HOOKS.md) for customization\n\n**Analytics (File-Based):**\n- Reads Claude Code usage data from `~/.claude/projects/**/*.jsonl`\n- Tracks tokens, costs, sessions, and model usage\n- Auto-updates every 30 seconds\n- Based on [Claude-Code-Usage-Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor)\n\n**Data Storage:**\n- Settings: `~/Library/Application Support/claudecode-macmenu/settings.json`\n- Hooks config: `~/.config/claude-code/hooks.json`\n- Usage data: `~/.claude/projects/**/*.jsonl` (read-only)\n","funding_links":[],"categories":["Tools \u0026 Utilities"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPiXeL16%2Fclaudecode-macmenu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPiXeL16%2Fclaudecode-macmenu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPiXeL16%2Fclaudecode-macmenu/lists"}