Claudence

Claudence is a macOS menu bar app for checking Claude usage at a glance.

It shows your current session usage, weekly usage, reset timing, basic pacing guidance, and whether the app is showing live data or saved fallback data.

What It Does

• lives in the macOS menu bar
• fetches Claude usage from the Claude web app using your saved sessionKey
• shows session and weekly usage in a compact popover
• shows reset timing for both cycles when Claude provides it
• falls back to the last saved snapshot when live refresh fails
• keeps a local history of successful snapshots for pacing and recent trend review
• includes a settings window for auth, display, usage, and diagnostics
• includes a diagnostics view for recent sync health

Current State

Implemented now:

• live fetch from Claude web endpoints
• Keychain-backed session key storage
• saved snapshot fallback
• automatic refresh and retry with backoff
• menu bar display modes
• setup-required flow
• local usage history
• basic trend summary in Settings

Still incomplete:

• notifications and warning delivery
• deeper onboarding polish
• broader integration hardening against Claude-side changes
• automated test coverage

Screenshots

Menu Bar Popover

Settings

About

How It Works

Claudence uses the sessionKey from your signed-in Claude browser session.

1. Sign in to Claude in your browser.
2. Copy the sessionKey cookie value from that session.
3. Open Claudence Settings.
4. Paste the key and save it.
5. Refresh to load live usage.

If live fetch fails, Claudence can keep showing the last saved snapshot and label it as saved data.

For a full setup walkthrough, see docs/SESSION_KEY_GUIDE.md.

Run Locally

1. Open Claudence.xcodeproj.
2. Run the Claudence scheme on My Mac.
3. Open the menu bar item.
4. Go to Settings.
5. Paste your Claude sessionKey.
6. Click Refresh.

You can also build from the command line:

swift build

Install For Normal Use

The source repo is for development. If you just want to use the app, the intended path is a built release from GitHub Releases.

For the first public release, the planned download format is a zipped Claudence.app. A signed/notarized .dmg can follow later.

Important: do not use the GitHub source-code zip for normal installation. That download only contains the project files and still requires Xcode. For normal use, download the app zip from the repo's Releases page.

Release install flow:

1. Download the latest Claudence release.
2. Move Claudence.app into /Applications.
3. Open the app once.
4. Paste your Claude sessionKey in Settings.
5. Optionally enable Launch at Login in Settings so the menu bar app starts automatically after sign-in.

Until release artifacts are published, running from source still requires Xcode.

Uninstall

To remove Claudence from your Mac:

1. Open Claudence and turn off Launch at Login in Settings if it is enabled.
2. Quit Claudence from the menu bar.
3. Delete Claudence.app from /Applications.

If you also want to remove local data:

• delete Claudence settings, snapshots, diagnostics, and history from ~/Library/Application Support/Claudence/
• remove the saved Claude sessionKey from macOS Keychain

Limitations

• This is not an official Claude client.
• It depends on Claude web session auth, which may expire or change.
• Claude-side payload changes may break live fetches until the app is updated.
• Local history is stored on-device only.

Public Release Checklist

See docs/PUBLIC_RELEASE_CHECKLIST.md for the tracked checklist of what is already complete and what still needs to be finished before this is ready for a confident public GitHub release.

Documentation

• docs/INDEX.md
• docs/REPO_METADATA.md
• docs/RELEASE_PROCESS.md
• docs/SESSION_KEY_GUIDE.md
• docs/PROJECT_BRIEF.md
• docs/ARCHITECTURE.md
• docs/PRODUCT_RULES.md
• docs/ROADMAP.md
• docs/HANDOFF.md
• docs/DECISIONS.md
• docs/WORKLOG/

License

MIT. See LICENSE.