Claude Usage

A lightweight desktop app (macOS only) for displaying Claude Code usage limits.

Built with Tauri v2, TypeScript, and Rust.

Features

• Auto-refresh functionality
• Color-coded status indicators (Green/Yellow/Red based on usage)
• Time until reset for session and weekly limits
• Multiple limit types: Session (5-hour), Weekly (7-day), and Sonnet-only
• Lightweight native performance
• Privacy-first: credentials never leave your machine
• Menubar-only app (no dock icon)

Installation

Local Build

This is the recommended path. It is the least annoying option for an unsigned hobby app.

1. Build the app:

   npm run tauri build

2. Quit Claude Usage if it is already running.

3. Copy the built app bundle into Applications:

   cp -R "src-tauri/target/release/bundle/macos/Claude Usage.app" /Applications/

4. If Finder asks whether to replace the existing app, choose Replace.

5. Launch /Applications/Claude Usage.app.

Gatekeeper

Because the app is not notarized, macOS may still block it on first launch. If that happens, the most reliable workaround is:

xattr -dr com.apple.quarantine "/Applications/Claude Usage.app"

Then launch the app again.

Releases

If a GitHub release includes a working .app or .dmg, you can use that, but this is the more annoying path on macOS.

For GitHub Users

1. Build from source locally.

   This is the smoothest option for an unsigned hobby app, because the locally built app does not arrive with the browser-downloaded quarantine flag.

   git clone https://github.com/pugstro/claude-usage-tauri.git
   cd claude-usage-tauri
   npm install
   npm run tauri build
   cp -R "src-tauri/target/release/bundle/macos/Claude Usage.app" /Applications/

2. Download a prebuilt .app or .dmg from GitHub Releases.

   This is convenient, but macOS Gatekeeper may block it because the app is not notarized. Expect at least one extra manual step. They will usually need to either:

   • go to System Settings > Privacy & Security and click Open Anyway, or
   • remove the quarantine flag manually:

   xattr -dr com.apple.quarantine "/Applications/Claude Usage.app"

Requirements

• macOS 13.0 (Ventura) or later
• Apple Silicon (M1/M2/M3) or Intel Mac
• Claude Code CLI installed and logged in

Setup

1. Install Claude Code if you haven't already:

   npm install -g @anthropic-ai/claude-code

2. Log in to Claude Code:

   claude

3. Launch Claude Usage - it will automatically read your credentials from Keychain

How It Works

Claude Usage reads your Claude Code OAuth credentials from macOS Keychain and queries the usage API endpoint at api.anthropic.com/api/oauth/usage.

Note: This uses an undocumented API that could change at any time. The app will gracefully handle API changes but may stop working if Anthropic modifies the endpoint.

Privacy

• Your credentials never leave your machine
• No analytics or telemetry
• No data sent anywhere except Anthropic's API
• Open source - verify the code yourself

Development

Prerequisites

• Node.js 18+ and npm
• Rust (install via rustup)

Setup

1. Clone the repository:

   git clone https://github.com/pugstro/claude-usage-tauri.git
   cd claude-usage-tauri

2. Install dependencies:

   npm install

3. Run development server:

   npm run tauri dev

Build

Build for production:

npm run tauri build

The built app bundle will be at:

src-tauri/target/release/bundle/macos/Claude Usage.app

Note: the DMG step may fail even when the .app bundle is built successfully.

Project Structure

claude-usage-tauri/
├── src/              # Frontend TypeScript/HTML/CSS
│   ├── main.ts      # Main application logic
│   └── styles.css   # Styling
├── src-tauri/       # Rust backend
│   ├── src/
│   │   ├── main.rs  # Entry point
│   │   └── lib.rs   # Tauri commands and app setup
│   ├── Cargo.toml   # Rust dependencies
│   └── tauri.conf.json  # Tauri configuration
└── package.json      # Node.js dependencies

Troubleshooting

"Not logged in to Claude Code"

Run claude in Terminal and complete the login flow.

"Authentication expired"

Your Claude Code session may have expired. Run claude again to re-authenticate.

App doesn't appear in menubar

Check if the app is running in Activity Monitor. Try quitting and reopening.

Usage shows wrong values

Click the refresh button in the dropdown. If still wrong, your Claude Code session may have expired - run claude again.

"App is damaged" error

This is macOS Gatekeeper blocking an unsigned app. If Right-click → Open is not enough, run:

xattr -dr com.apple.quarantine "/Applications/Claude Usage.app"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This is an unofficial tool not affiliated with Anthropic. It uses an undocumented API that may change without notice.

Credits

• Built with Tauri
• Inspired by the Swift-based claudecodeusage app

---

Made by pugstro