Skip to content

Commit f451b66

Browse files
Priyans-huPriyans-hu
authored
Merge pull request #9 from Priyans-hu/chore/community-and-llm-files
Add community files and LLM helper docs
2 parents 01ddfc4 + cfa287c commit f451b66

File tree

11 files changed

+327
-4
lines changed

11 files changed

+327
-4
lines changed

‎.cursorrules‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
You are working on TokenMeter, a macOS menu bar app for tracking Claude Code usage.
2+
3+
## Tech Stack
4+
- Swift 5.9+, SwiftUI, macOS 14+
5+
- Swift Package Manager (no Xcode project)
6+
- Swift Concurrency (async/await, actors, @MainActor)
7+
8+
## Build
9+
cd TokenMeter && swift build -c release
10+
11+
## Key Files
12+
- TokenMeterApp.swift — MenuBarExtra app entry
13+
- UsageViewModel.swift — @MainActor ObservableObject, state management
14+
- Services/NativeUsageParser.swift — JSONL parser for ~/.claude/projects/
15+
- Services/UsageAPIService.swift — Keychain reader + Anthropic API client
16+
- Models/UsageSummary.swift — All data models and ClaudePlan enum
17+
- Views/ — SwiftUI views (dashboard, rate limits, heatmap, charts, settings)
18+
19+
## Patterns
20+
- UsageAPIService is an actor (thread-safe)
21+
- UsageViewModel is @MainActor (UI-bound)
22+
- API + local JSONL parsing run concurrently via async let
23+
- API data preferred for rate limits, local JSONL for costs/breakdowns
24+
- UserDefaults for caching and settings persistence
25+
- UNUserNotificationCenter for rate limit alerts
26+
27+
## Guidelines
28+
- Keep the app lightweight — it runs in the menu bar
29+
- No Xcode project files — use SPM only
30+
- macOS 14+ minimum (for MenuBarExtra)
31+
- Verify changes compile: swift build -c release

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug in TokenMeter
4+
title: ''
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
**Describe the bug**
10+
A clear description of what the bug is.
11+
12+
**To Reproduce**
13+
Steps to reproduce the behavior:
14+
1. ...
15+
2. ...
16+
17+
**Expected behavior**
18+
What you expected to happen.
19+
20+
**Screenshots**
21+
If applicable, add screenshots.
22+
23+
**Environment:**
24+
- macOS version: [e.g. 15.2]
25+
- TokenMeter version: [e.g. 0.3.0]
26+
- Claude Plan: [e.g. Pro, Max 5x, Max 20x]
27+
- Install method: [Homebrew / install script / manual]
28+
29+
**Additional context**
30+
Any other context about the problem.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: Feature Request
3+
about: Suggest a feature for TokenMeter
4+
title: ''
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
**Problem**
10+
What problem does this solve? E.g. "I'm frustrated when..."
11+
12+
**Proposed Solution**
13+
How should this work?
14+
15+
**Alternatives Considered**
16+
Any other approaches you've thought of.
17+
18+
**Additional context**
19+
Screenshots, mockups, or references.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## Summary
2+
<!-- Brief description of what this PR does -->
3+
4+
## Changes
5+
-
6+
7+
## Test Plan
8+
- [ ] `swift build -c release` passes
9+
- [ ] App launches and works correctly
10+
- [ ]
11+
12+
## Screenshots
13+
<!-- If UI changes, add before/after screenshots -->

‎.github/copilot-instructions.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# TokenMeter — Copilot Instructions
2+
3+
macOS menu bar app for tracking Claude Code usage, rate limits, and costs.
4+
5+
## Tech Stack
6+
- Swift 5.9+, SwiftUI, macOS 14+ (Sonoma)
7+
- Swift Package Manager — `cd TokenMeter && swift build -c release`
8+
- Swift Concurrency — async/await, actors, @MainActor
9+
10+
## Architecture
11+
- `TokenMeterApp.swift` — MenuBarExtra app entry point
12+
- `UsageViewModel.swift` — @MainActor ObservableObject for all state
13+
- `Services/NativeUsageParser.swift` — parses JSONL from ~/.claude/projects/
14+
- `Services/UsageAPIService.swift` — actor, reads Keychain OAuth token, calls Anthropic API
15+
- `Models/UsageSummary.swift` — data models (DailyUsage, HourlyUsage, RateLimitInfo, ClaudePlan)
16+
- `Views/` — SwiftUI views
17+
18+
## Conventions
19+
- UsageAPIService is an `actor` for thread safety
20+
- UsageViewModel is `@MainActor` for UI updates
21+
- Concurrent data fetching with `async let`
22+
- No Xcode project — SPM only
23+
- macOS 14+ minimum deployment target

‎.windsurfrules‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
You are working on TokenMeter, a native macOS menu bar app for tracking Claude Code usage.
2+
3+
Tech: Swift 5.9+, SwiftUI, macOS 14+, Swift Package Manager
4+
Build: cd TokenMeter && swift build -c release
5+
6+
Architecture:
7+
- TokenMeterApp.swift — MenuBarExtra entry point
8+
- UsageViewModel.swift — @MainActor ObservableObject, manages state/timer/cache/notifications
9+
- Services/NativeUsageParser.swift — JSONL parser for ~/.claude/projects/
10+
- Services/UsageAPIService.swift — actor, Keychain + Anthropic API
11+
- Models/UsageSummary.swift — data models, ClaudePlan enum
12+
- Views/ — SwiftUI views
13+
14+
Patterns:
15+
- actor for services, @MainActor for view model
16+
- async let for concurrent API + local data fetch
17+
- API data preferred for rate limits, JSONL for costs
18+
- UserDefaults for caching, UNUserNotificationCenter for alerts
19+
- No Xcode project, SPM only

‎CLAUDE.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# TokenMeter
2+
3+
macOS menu bar app for tracking Claude Code usage, rate limits, and costs. Native SwiftUI, no Electron/Tauri.
4+
5+
## Build
6+
7+
```bash
8+
cd TokenMeter
9+
swift build -c release
10+
```
11+
12+
Binary output: `TokenMeter/.build/release/TokenMeter`
13+
14+
## Architecture
15+
16+
- **SwiftUI MenuBarExtra** — macOS 14+, `LSUIElement` (no dock icon)
17+
- **Swift Package Manager** — single executable target, no Xcode project
18+
- **Concurrency** — `@MainActor` view model, `actor` for services, `async let` for parallel fetches
19+
20+
### Key Components
21+
22+
| File | Role |
23+
|------|------|
24+
| `TokenMeterApp.swift` | App entry, `MenuBarExtra` with popover |
25+
| `UsageViewModel.swift` | `@MainActor ObservableObject` — state, timer, caching, notifications |
26+
| `Services/NativeUsageParser.swift` | Parses `~/.claude/projects/**/*.jsonl` — costs, tokens, hourly data |
27+
| `Services/UsageAPIService.swift` | Reads OAuth token from macOS Keychain, calls `api.anthropic.com/api/oauth/usage` |
28+
| `Services/UpdateChecker.swift` | Checks GitHub releases for updates |
29+
| `Models/UsageSummary.swift` | All data models: `DailyUsage`, `HourlyUsage`, `RateLimitInfo`, `ClaudePlan` |
30+
| `Views/` | SwiftUI views — dashboard, rate limits, heatmap, charts, settings |
31+
32+
### Data Sources
33+
34+
1. **Anthropic API** (`UsageAPIService`) — real rate limit utilization % and reset times
35+
- Reads OAuth token from Keychain (`kSecAttrService: "Claude Code-credentials"`)
36+
- `GET https://api.anthropic.com/api/oauth/usage` with `Authorization: Bearer <token>`
37+
- Also reads `rateLimitTier` from credential blob for plan auto-detection
38+
39+
2. **Local JSONL** (`NativeUsageParser`) — costs, model breakdowns, token counts, hourly activity
40+
- Scans `~/.claude/projects/` and `~/.config/claude/projects/`
41+
- Deduplicates by `requestId`, filters `<synthetic>` entries
42+
- Embedded pricing: Opus 4.5 ($5/$25), Sonnet ($3/$15), Haiku ($1/$5) per MTok
43+
44+
### Patterns
45+
46+
- API + local data fetched concurrently via `async let` in `refresh()`
47+
- API data preferred for rate limits; local data used as fallback
48+
- `UserDefaults` for caching summary + settings
49+
- `UNUserNotificationCenter` for rate limit alerts (80% threshold, 1hr throttle)
50+
- Timer-based auto-refresh (default 5 min)
51+
52+
## Release
53+
54+
Push a version tag to trigger automated release:
55+
```bash
56+
git tag v0.x.0
57+
git push origin v0.x.0
58+
```
59+
60+
GitHub Actions builds, ad-hoc signs, creates release zip, and updates Homebrew cask.
61+
62+
## Install
63+
64+
```bash
65+
brew install Priyans-hu/tap/tokenmeter
66+
```

‎CODE_OF_CONDUCT.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Code of Conduct
2+
3+
## Our Pledge
4+
5+
We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
6+
7+
## Our Standards
8+
9+
**Positive behavior includes:**
10+
- Using welcoming and inclusive language
11+
- Respecting differing viewpoints and experiences
12+
- Accepting constructive criticism gracefully
13+
- Focusing on what is best for the community
14+
15+
**Unacceptable behavior includes:**
16+
- Trolling, insulting/derogatory comments, and personal attacks
17+
- Public or private harassment
18+
- Publishing others' private information without permission
19+
- Other conduct which could reasonably be considered inappropriate
20+
21+
## Enforcement
22+
23+
Project maintainers are responsible for clarifying standards of acceptable behavior and may take appropriate corrective action in response to unacceptable behavior.
24+
25+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainer at [email protected].
26+
27+
## Attribution
28+
29+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

‎CONTRIBUTING.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Contributing to TokenMeter
2+
3+
Thanks for your interest in contributing to TokenMeter!
4+
5+
## Getting Started
6+
7+
1. Fork and clone the repo
8+
2. Build the project:
9+
```bash
10+
cd TokenMeter
11+
swift build -c release
12+
```
13+
3. Create a feature branch: `git checkout -b feat/my-feature`
14+
15+
## Development
16+
17+
### Requirements
18+
- macOS 14 (Sonoma) or later
19+
- Swift 5.9+
20+
- Claude Code installed (for testing with real data)
21+
22+
### Project Structure
23+
```
24+
TokenMeter/
25+
├── TokenMeterApp.swift # App entry with MenuBarExtra
26+
├── UsageViewModel.swift # State, timer, caching, notifications
27+
├── Models/
28+
│ └── UsageSummary.swift # Data models + ClaudePlan enum
29+
├── Services/
30+
│ ├── NativeUsageParser.swift # JSONL parser + pricing engine
31+
│ ├── UsageAPIService.swift # Keychain + Anthropic API client
32+
│ └── UpdateChecker.swift # GitHub releases checker
33+
└── Views/ # SwiftUI views
34+
```
35+
36+
### Building and Testing
37+
38+
```bash
39+
cd TokenMeter
40+
swift build -c release
41+
```
42+
43+
To install locally for testing:
44+
```bash
45+
cp .build/release/TokenMeter /Applications/TokenMeter.app/Contents/MacOS/TokenMeter
46+
```
47+
48+
## Submitting Changes
49+
50+
1. Ensure `swift build -c release` passes
51+
2. Keep commits focused and atomic
52+
3. Write clear commit messages
53+
4. Submit a PR to `main`
54+
55+
## Reporting Issues
56+
57+
- Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) for bugs
58+
- Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) for new ideas
59+
60+
## License
61+
62+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎README.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ Reads Claude Code's OAuth token from Keychain for real rate limit data, and pars
66

77
![macOS](https://img.shields.io/badge/macOS_14+-000?logo=apple&logoColor=white)
88
![SwiftUI](https://img.shields.io/badge/SwiftUI-007AFF?logo=swift&logoColor=white)
9+
![Downloads](https://img.shields.io/github/downloads/Priyans-hu/tokenmeter/total)
10+
![License](https://img.shields.io/github/license/Priyans-hu/tokenmeter)
911

1012
## Features
1113

@@ -127,7 +129,8 @@ MIT License. See [LICENSE](LICENSE) for details.
127129

128130
## Contributing
129131

130-
1. Fork and clone the repo
131-
2. Create a feature branch: `git checkout -b feat/my-feature`
132-
3. Build: `cd TokenMeter && swift build -c release`
133-
4. Submit a PR to `main`
132+
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
133+
134+
## Security
135+
136+
See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.

0 commit comments

Comments
 (0)