claude-code-usage 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- claude_code_usage-1.0.0/LICENSE +21 -0
- claude_code_usage-1.0.0/PKG-INFO +187 -0
- claude_code_usage-1.0.0/README.md +161 -0
- claude_code_usage-1.0.0/claude_code_usage.egg-info/PKG-INFO +187 -0
- claude_code_usage-1.0.0/claude_code_usage.egg-info/SOURCES.txt +18 -0
- claude_code_usage-1.0.0/claude_code_usage.egg-info/dependency_links.txt +1 -0
- claude_code_usage-1.0.0/claude_code_usage.egg-info/entry_points.txt +5 -0
- claude_code_usage-1.0.0/claude_code_usage.egg-info/requires.txt +2 -0
- claude_code_usage-1.0.0/claude_code_usage.egg-info/top_level.txt +1 -0
- claude_code_usage-1.0.0/pyproject.toml +45 -0
- claude_code_usage-1.0.0/setup.cfg +4 -0
- claude_code_usage-1.0.0/src/__init__.py +1 -0
- claude_code_usage-1.0.0/src/api.py +202 -0
- claude_code_usage-1.0.0/src/autostart.py +94 -0
- claude_code_usage-1.0.0/src/config.py +173 -0
- claude_code_usage-1.0.0/src/icon_generator.py +92 -0
- claude_code_usage-1.0.0/src/main.py +24 -0
- claude_code_usage-1.0.0/src/notifier.py +289 -0
- claude_code_usage-1.0.0/src/tray.py +302 -0
- claude_code_usage-1.0.0/src/utils.py +35 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Max
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: claude-code-usage
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: System tray monitor for Claude Code token usage
|
|
5
|
+
Author: Max
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Maex-z9/CC_Usage
|
|
8
|
+
Project-URL: Repository, https://github.com/Maex-z9/CC_Usage
|
|
9
|
+
Project-URL: Issues, https://github.com/Maex-z9/CC_Usage/issues
|
|
10
|
+
Keywords: claude,anthropic,usage,monitor,tray,gnome
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: X11 Applications :: GTK
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Utilities
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: requests>=2.28.0
|
|
24
|
+
Requires-Dist: PyGObject>=3.42.0
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
# Claude Code Usage Overlay
|
|
28
|
+
|
|
29
|
+
A Linux/GNOME system tray application that monitors your Claude Code token usage and alerts you before hitting limits.
|
|
30
|
+
|
|
31
|
+

|
|
32
|
+

|
|
33
|
+

|
|
34
|
+
|
|
35
|
+
## Features
|
|
36
|
+
|
|
37
|
+
- **System tray icon** with color-coded gauge (green/yellow/red based on usage)
|
|
38
|
+
- **Panel label** showing session and weekly usage percentages
|
|
39
|
+
- **Popup notifications** at configurable thresholds (default: 50%, 75%, 90%)
|
|
40
|
+
- **Configurable settings** via JSON file or Settings menu
|
|
41
|
+
- **Auto-start on login** via XDG autostart
|
|
42
|
+
|
|
43
|
+
## Screenshots
|
|
44
|
+
|
|
45
|
+
The tray icon shows your current usage with:
|
|
46
|
+
- Arc fill = session usage (5-hour window)
|
|
47
|
+
- Color = worst-case urgency (max of session/weekly)
|
|
48
|
+
- Panel label = "45%|67%" format
|
|
49
|
+
|
|
50
|
+
## Requirements
|
|
51
|
+
|
|
52
|
+
- Linux with GNOME Shell (or compatible desktop with AppIndicator support)
|
|
53
|
+
- Python 3.11+
|
|
54
|
+
- [Claude Code CLI](https://claude.ai/code) installed and authenticated
|
|
55
|
+
- AppIndicator extension for GNOME Shell
|
|
56
|
+
|
|
57
|
+
### System Dependencies
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
# Ubuntu/Debian
|
|
61
|
+
sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7
|
|
62
|
+
|
|
63
|
+
# Fedora
|
|
64
|
+
sudo dnf install python3-gobject python3-cairo libayatana-appindicator-gtk3 libnotify
|
|
65
|
+
|
|
66
|
+
# Arch
|
|
67
|
+
sudo pacman -S python-gobject python-cairo libayatana-appindicator libnotify
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### GNOME Shell Extension
|
|
71
|
+
|
|
72
|
+
Install the [AppIndicator Support](https://extensions.gnome.org/extension/615/appindicator-support/) extension for GNOME Shell to see system tray icons.
|
|
73
|
+
|
|
74
|
+
## Installation
|
|
75
|
+
|
|
76
|
+
### Quick Install (recommended)
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
git clone https://github.com/Maex-z9/CC_Usage.git
|
|
80
|
+
cd CC_Usage
|
|
81
|
+
./install.sh
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
This installs system dependencies and the app. Then run with: `claude-usage`
|
|
85
|
+
|
|
86
|
+
### Manual Install
|
|
87
|
+
|
|
88
|
+
1. Install system dependencies:
|
|
89
|
+
```bash
|
|
90
|
+
# Ubuntu/Debian
|
|
91
|
+
sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7
|
|
92
|
+
|
|
93
|
+
# Fedora
|
|
94
|
+
sudo dnf install python3-gobject python3-cairo libayatana-appindicator-gtk3 libnotify
|
|
95
|
+
|
|
96
|
+
# Arch
|
|
97
|
+
sudo pacman -S python-gobject python-cairo libayatana-appindicator libnotify
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
2. Install the app:
|
|
101
|
+
```bash
|
|
102
|
+
pip install git+https://github.com/Maex-z9/CC_Usage.git
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
3. Authenticate with Claude Code (if not already done):
|
|
106
|
+
```bash
|
|
107
|
+
claude
|
|
108
|
+
# Follow the authentication flow
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Usage
|
|
112
|
+
|
|
113
|
+
Run the application:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
claude-usage
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Or if running from source:
|
|
120
|
+
```bash
|
|
121
|
+
python3 -m src.main
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Menu Options
|
|
125
|
+
|
|
126
|
+
Click the tray icon to access:
|
|
127
|
+
- Current usage percentages and reset time
|
|
128
|
+
- **Refresh** - Force update usage data
|
|
129
|
+
- **Settings** submenu:
|
|
130
|
+
- Pause Notifications - Temporarily disable alerts
|
|
131
|
+
- Autostart on Login - Enable/disable auto-start
|
|
132
|
+
- Edit Config File - Open config in text editor
|
|
133
|
+
- **Quit** - Exit the application
|
|
134
|
+
|
|
135
|
+
### Configuration
|
|
136
|
+
|
|
137
|
+
Config file location: `~/.config/claude-usage-overlay/config.json`
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"session_thresholds": [50, 75, 90],
|
|
142
|
+
"weekly_thresholds": [50, 75, 90],
|
|
143
|
+
"polling_interval": 300,
|
|
144
|
+
"pause_notifications": false,
|
|
145
|
+
"autostart_enabled": false
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
| Setting | Description | Default |
|
|
150
|
+
|---------|-------------|---------|
|
|
151
|
+
| `session_thresholds` | Alert thresholds for 5-hour session usage | `[50, 75, 90]` |
|
|
152
|
+
| `weekly_thresholds` | Alert thresholds for 7-day weekly usage | `[50, 75, 90]` |
|
|
153
|
+
| `polling_interval` | Seconds between API checks (30-3600) | `300` (5 min) |
|
|
154
|
+
| `pause_notifications` | Disable popup alerts | `false` |
|
|
155
|
+
| `autostart_enabled` | Start on login | `false` |
|
|
156
|
+
|
|
157
|
+
## How It Works
|
|
158
|
+
|
|
159
|
+
1. Reads your OAuth token from `~/.claude/.credentials.json` (created by Claude Code CLI)
|
|
160
|
+
2. Polls the Anthropic usage API every 5 minutes (configurable)
|
|
161
|
+
3. Displays usage in the system tray with color-coded urgency
|
|
162
|
+
4. Shows desktop notifications when thresholds are crossed
|
|
163
|
+
|
|
164
|
+
## Privacy & Security
|
|
165
|
+
|
|
166
|
+
- **No API keys stored in the repo** - Uses Claude Code's existing credentials
|
|
167
|
+
- **Credentials stay local** - Reads from `~/.claude/.credentials.json`
|
|
168
|
+
- **Config stays local** - Stored in `~/.config/claude-usage-overlay/`
|
|
169
|
+
- **No data sent anywhere** - Only communicates with Anthropic's API
|
|
170
|
+
|
|
171
|
+
## Known Issues
|
|
172
|
+
|
|
173
|
+
See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for details on:
|
|
174
|
+
- GNOME Shell tooltip limitations (using panel label instead)
|
|
175
|
+
- AppIndicator menu accelerator limitations
|
|
176
|
+
|
|
177
|
+
## Contributing
|
|
178
|
+
|
|
179
|
+
Contributions welcome! Please open an issue or PR.
|
|
180
|
+
|
|
181
|
+
## License
|
|
182
|
+
|
|
183
|
+
MIT License - See [LICENSE](LICENSE) for details.
|
|
184
|
+
|
|
185
|
+
## Acknowledgments
|
|
186
|
+
|
|
187
|
+
Built with [Claude Code](https://claude.ai/code) using the [GSD workflow](https://github.com/get-shit-done/gsd).
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
# Claude Code Usage Overlay
|
|
2
|
+
|
|
3
|
+
A Linux/GNOME system tray application that monitors your Claude Code token usage and alerts you before hitting limits.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+

|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **System tray icon** with color-coded gauge (green/yellow/red based on usage)
|
|
12
|
+
- **Panel label** showing session and weekly usage percentages
|
|
13
|
+
- **Popup notifications** at configurable thresholds (default: 50%, 75%, 90%)
|
|
14
|
+
- **Configurable settings** via JSON file or Settings menu
|
|
15
|
+
- **Auto-start on login** via XDG autostart
|
|
16
|
+
|
|
17
|
+
## Screenshots
|
|
18
|
+
|
|
19
|
+
The tray icon shows your current usage with:
|
|
20
|
+
- Arc fill = session usage (5-hour window)
|
|
21
|
+
- Color = worst-case urgency (max of session/weekly)
|
|
22
|
+
- Panel label = "45%|67%" format
|
|
23
|
+
|
|
24
|
+
## Requirements
|
|
25
|
+
|
|
26
|
+
- Linux with GNOME Shell (or compatible desktop with AppIndicator support)
|
|
27
|
+
- Python 3.11+
|
|
28
|
+
- [Claude Code CLI](https://claude.ai/code) installed and authenticated
|
|
29
|
+
- AppIndicator extension for GNOME Shell
|
|
30
|
+
|
|
31
|
+
### System Dependencies
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Ubuntu/Debian
|
|
35
|
+
sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7
|
|
36
|
+
|
|
37
|
+
# Fedora
|
|
38
|
+
sudo dnf install python3-gobject python3-cairo libayatana-appindicator-gtk3 libnotify
|
|
39
|
+
|
|
40
|
+
# Arch
|
|
41
|
+
sudo pacman -S python-gobject python-cairo libayatana-appindicator libnotify
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### GNOME Shell Extension
|
|
45
|
+
|
|
46
|
+
Install the [AppIndicator Support](https://extensions.gnome.org/extension/615/appindicator-support/) extension for GNOME Shell to see system tray icons.
|
|
47
|
+
|
|
48
|
+
## Installation
|
|
49
|
+
|
|
50
|
+
### Quick Install (recommended)
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
git clone https://github.com/Maex-z9/CC_Usage.git
|
|
54
|
+
cd CC_Usage
|
|
55
|
+
./install.sh
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
This installs system dependencies and the app. Then run with: `claude-usage`
|
|
59
|
+
|
|
60
|
+
### Manual Install
|
|
61
|
+
|
|
62
|
+
1. Install system dependencies:
|
|
63
|
+
```bash
|
|
64
|
+
# Ubuntu/Debian
|
|
65
|
+
sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7
|
|
66
|
+
|
|
67
|
+
# Fedora
|
|
68
|
+
sudo dnf install python3-gobject python3-cairo libayatana-appindicator-gtk3 libnotify
|
|
69
|
+
|
|
70
|
+
# Arch
|
|
71
|
+
sudo pacman -S python-gobject python-cairo libayatana-appindicator libnotify
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
2. Install the app:
|
|
75
|
+
```bash
|
|
76
|
+
pip install git+https://github.com/Maex-z9/CC_Usage.git
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
3. Authenticate with Claude Code (if not already done):
|
|
80
|
+
```bash
|
|
81
|
+
claude
|
|
82
|
+
# Follow the authentication flow
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Usage
|
|
86
|
+
|
|
87
|
+
Run the application:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
claude-usage
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Or if running from source:
|
|
94
|
+
```bash
|
|
95
|
+
python3 -m src.main
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Menu Options
|
|
99
|
+
|
|
100
|
+
Click the tray icon to access:
|
|
101
|
+
- Current usage percentages and reset time
|
|
102
|
+
- **Refresh** - Force update usage data
|
|
103
|
+
- **Settings** submenu:
|
|
104
|
+
- Pause Notifications - Temporarily disable alerts
|
|
105
|
+
- Autostart on Login - Enable/disable auto-start
|
|
106
|
+
- Edit Config File - Open config in text editor
|
|
107
|
+
- **Quit** - Exit the application
|
|
108
|
+
|
|
109
|
+
### Configuration
|
|
110
|
+
|
|
111
|
+
Config file location: `~/.config/claude-usage-overlay/config.json`
|
|
112
|
+
|
|
113
|
+
```json
|
|
114
|
+
{
|
|
115
|
+
"session_thresholds": [50, 75, 90],
|
|
116
|
+
"weekly_thresholds": [50, 75, 90],
|
|
117
|
+
"polling_interval": 300,
|
|
118
|
+
"pause_notifications": false,
|
|
119
|
+
"autostart_enabled": false
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
| Setting | Description | Default |
|
|
124
|
+
|---------|-------------|---------|
|
|
125
|
+
| `session_thresholds` | Alert thresholds for 5-hour session usage | `[50, 75, 90]` |
|
|
126
|
+
| `weekly_thresholds` | Alert thresholds for 7-day weekly usage | `[50, 75, 90]` |
|
|
127
|
+
| `polling_interval` | Seconds between API checks (30-3600) | `300` (5 min) |
|
|
128
|
+
| `pause_notifications` | Disable popup alerts | `false` |
|
|
129
|
+
| `autostart_enabled` | Start on login | `false` |
|
|
130
|
+
|
|
131
|
+
## How It Works
|
|
132
|
+
|
|
133
|
+
1. Reads your OAuth token from `~/.claude/.credentials.json` (created by Claude Code CLI)
|
|
134
|
+
2. Polls the Anthropic usage API every 5 minutes (configurable)
|
|
135
|
+
3. Displays usage in the system tray with color-coded urgency
|
|
136
|
+
4. Shows desktop notifications when thresholds are crossed
|
|
137
|
+
|
|
138
|
+
## Privacy & Security
|
|
139
|
+
|
|
140
|
+
- **No API keys stored in the repo** - Uses Claude Code's existing credentials
|
|
141
|
+
- **Credentials stay local** - Reads from `~/.claude/.credentials.json`
|
|
142
|
+
- **Config stays local** - Stored in `~/.config/claude-usage-overlay/`
|
|
143
|
+
- **No data sent anywhere** - Only communicates with Anthropic's API
|
|
144
|
+
|
|
145
|
+
## Known Issues
|
|
146
|
+
|
|
147
|
+
See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for details on:
|
|
148
|
+
- GNOME Shell tooltip limitations (using panel label instead)
|
|
149
|
+
- AppIndicator menu accelerator limitations
|
|
150
|
+
|
|
151
|
+
## Contributing
|
|
152
|
+
|
|
153
|
+
Contributions welcome! Please open an issue or PR.
|
|
154
|
+
|
|
155
|
+
## License
|
|
156
|
+
|
|
157
|
+
MIT License - See [LICENSE](LICENSE) for details.
|
|
158
|
+
|
|
159
|
+
## Acknowledgments
|
|
160
|
+
|
|
161
|
+
Built with [Claude Code](https://claude.ai/code) using the [GSD workflow](https://github.com/get-shit-done/gsd).
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: claude-code-usage
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: System tray monitor for Claude Code token usage
|
|
5
|
+
Author: Max
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Maex-z9/CC_Usage
|
|
8
|
+
Project-URL: Repository, https://github.com/Maex-z9/CC_Usage
|
|
9
|
+
Project-URL: Issues, https://github.com/Maex-z9/CC_Usage/issues
|
|
10
|
+
Keywords: claude,anthropic,usage,monitor,tray,gnome
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: X11 Applications :: GTK
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Utilities
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: requests>=2.28.0
|
|
24
|
+
Requires-Dist: PyGObject>=3.42.0
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
# Claude Code Usage Overlay
|
|
28
|
+
|
|
29
|
+
A Linux/GNOME system tray application that monitors your Claude Code token usage and alerts you before hitting limits.
|
|
30
|
+
|
|
31
|
+

|
|
32
|
+

|
|
33
|
+

|
|
34
|
+
|
|
35
|
+
## Features
|
|
36
|
+
|
|
37
|
+
- **System tray icon** with color-coded gauge (green/yellow/red based on usage)
|
|
38
|
+
- **Panel label** showing session and weekly usage percentages
|
|
39
|
+
- **Popup notifications** at configurable thresholds (default: 50%, 75%, 90%)
|
|
40
|
+
- **Configurable settings** via JSON file or Settings menu
|
|
41
|
+
- **Auto-start on login** via XDG autostart
|
|
42
|
+
|
|
43
|
+
## Screenshots
|
|
44
|
+
|
|
45
|
+
The tray icon shows your current usage with:
|
|
46
|
+
- Arc fill = session usage (5-hour window)
|
|
47
|
+
- Color = worst-case urgency (max of session/weekly)
|
|
48
|
+
- Panel label = "45%|67%" format
|
|
49
|
+
|
|
50
|
+
## Requirements
|
|
51
|
+
|
|
52
|
+
- Linux with GNOME Shell (or compatible desktop with AppIndicator support)
|
|
53
|
+
- Python 3.11+
|
|
54
|
+
- [Claude Code CLI](https://claude.ai/code) installed and authenticated
|
|
55
|
+
- AppIndicator extension for GNOME Shell
|
|
56
|
+
|
|
57
|
+
### System Dependencies
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
# Ubuntu/Debian
|
|
61
|
+
sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7
|
|
62
|
+
|
|
63
|
+
# Fedora
|
|
64
|
+
sudo dnf install python3-gobject python3-cairo libayatana-appindicator-gtk3 libnotify
|
|
65
|
+
|
|
66
|
+
# Arch
|
|
67
|
+
sudo pacman -S python-gobject python-cairo libayatana-appindicator libnotify
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### GNOME Shell Extension
|
|
71
|
+
|
|
72
|
+
Install the [AppIndicator Support](https://extensions.gnome.org/extension/615/appindicator-support/) extension for GNOME Shell to see system tray icons.
|
|
73
|
+
|
|
74
|
+
## Installation
|
|
75
|
+
|
|
76
|
+
### Quick Install (recommended)
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
git clone https://github.com/Maex-z9/CC_Usage.git
|
|
80
|
+
cd CC_Usage
|
|
81
|
+
./install.sh
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
This installs system dependencies and the app. Then run with: `claude-usage`
|
|
85
|
+
|
|
86
|
+
### Manual Install
|
|
87
|
+
|
|
88
|
+
1. Install system dependencies:
|
|
89
|
+
```bash
|
|
90
|
+
# Ubuntu/Debian
|
|
91
|
+
sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7
|
|
92
|
+
|
|
93
|
+
# Fedora
|
|
94
|
+
sudo dnf install python3-gobject python3-cairo libayatana-appindicator-gtk3 libnotify
|
|
95
|
+
|
|
96
|
+
# Arch
|
|
97
|
+
sudo pacman -S python-gobject python-cairo libayatana-appindicator libnotify
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
2. Install the app:
|
|
101
|
+
```bash
|
|
102
|
+
pip install git+https://github.com/Maex-z9/CC_Usage.git
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
3. Authenticate with Claude Code (if not already done):
|
|
106
|
+
```bash
|
|
107
|
+
claude
|
|
108
|
+
# Follow the authentication flow
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Usage
|
|
112
|
+
|
|
113
|
+
Run the application:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
claude-usage
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Or if running from source:
|
|
120
|
+
```bash
|
|
121
|
+
python3 -m src.main
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Menu Options
|
|
125
|
+
|
|
126
|
+
Click the tray icon to access:
|
|
127
|
+
- Current usage percentages and reset time
|
|
128
|
+
- **Refresh** - Force update usage data
|
|
129
|
+
- **Settings** submenu:
|
|
130
|
+
- Pause Notifications - Temporarily disable alerts
|
|
131
|
+
- Autostart on Login - Enable/disable auto-start
|
|
132
|
+
- Edit Config File - Open config in text editor
|
|
133
|
+
- **Quit** - Exit the application
|
|
134
|
+
|
|
135
|
+
### Configuration
|
|
136
|
+
|
|
137
|
+
Config file location: `~/.config/claude-usage-overlay/config.json`
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"session_thresholds": [50, 75, 90],
|
|
142
|
+
"weekly_thresholds": [50, 75, 90],
|
|
143
|
+
"polling_interval": 300,
|
|
144
|
+
"pause_notifications": false,
|
|
145
|
+
"autostart_enabled": false
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
| Setting | Description | Default |
|
|
150
|
+
|---------|-------------|---------|
|
|
151
|
+
| `session_thresholds` | Alert thresholds for 5-hour session usage | `[50, 75, 90]` |
|
|
152
|
+
| `weekly_thresholds` | Alert thresholds for 7-day weekly usage | `[50, 75, 90]` |
|
|
153
|
+
| `polling_interval` | Seconds between API checks (30-3600) | `300` (5 min) |
|
|
154
|
+
| `pause_notifications` | Disable popup alerts | `false` |
|
|
155
|
+
| `autostart_enabled` | Start on login | `false` |
|
|
156
|
+
|
|
157
|
+
## How It Works
|
|
158
|
+
|
|
159
|
+
1. Reads your OAuth token from `~/.claude/.credentials.json` (created by Claude Code CLI)
|
|
160
|
+
2. Polls the Anthropic usage API every 5 minutes (configurable)
|
|
161
|
+
3. Displays usage in the system tray with color-coded urgency
|
|
162
|
+
4. Shows desktop notifications when thresholds are crossed
|
|
163
|
+
|
|
164
|
+
## Privacy & Security
|
|
165
|
+
|
|
166
|
+
- **No API keys stored in the repo** - Uses Claude Code's existing credentials
|
|
167
|
+
- **Credentials stay local** - Reads from `~/.claude/.credentials.json`
|
|
168
|
+
- **Config stays local** - Stored in `~/.config/claude-usage-overlay/`
|
|
169
|
+
- **No data sent anywhere** - Only communicates with Anthropic's API
|
|
170
|
+
|
|
171
|
+
## Known Issues
|
|
172
|
+
|
|
173
|
+
See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for details on:
|
|
174
|
+
- GNOME Shell tooltip limitations (using panel label instead)
|
|
175
|
+
- AppIndicator menu accelerator limitations
|
|
176
|
+
|
|
177
|
+
## Contributing
|
|
178
|
+
|
|
179
|
+
Contributions welcome! Please open an issue or PR.
|
|
180
|
+
|
|
181
|
+
## License
|
|
182
|
+
|
|
183
|
+
MIT License - See [LICENSE](LICENSE) for details.
|
|
184
|
+
|
|
185
|
+
## Acknowledgments
|
|
186
|
+
|
|
187
|
+
Built with [Claude Code](https://claude.ai/code) using the [GSD workflow](https://github.com/get-shit-done/gsd).
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
claude_code_usage.egg-info/PKG-INFO
|
|
5
|
+
claude_code_usage.egg-info/SOURCES.txt
|
|
6
|
+
claude_code_usage.egg-info/dependency_links.txt
|
|
7
|
+
claude_code_usage.egg-info/entry_points.txt
|
|
8
|
+
claude_code_usage.egg-info/requires.txt
|
|
9
|
+
claude_code_usage.egg-info/top_level.txt
|
|
10
|
+
src/__init__.py
|
|
11
|
+
src/api.py
|
|
12
|
+
src/autostart.py
|
|
13
|
+
src/config.py
|
|
14
|
+
src/icon_generator.py
|
|
15
|
+
src/main.py
|
|
16
|
+
src/notifier.py
|
|
17
|
+
src/tray.py
|
|
18
|
+
src/utils.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
src
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "claude-code-usage"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "System tray monitor for Claude Code token usage"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = {text = "MIT"}
|
|
11
|
+
authors = [
|
|
12
|
+
{name = "Max"}
|
|
13
|
+
]
|
|
14
|
+
keywords = ["claude", "anthropic", "usage", "monitor", "tray", "gnome"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Environment :: X11 Applications :: GTK",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"License :: OSI Approved :: MIT License",
|
|
20
|
+
"Operating System :: POSIX :: Linux",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Topic :: Utilities",
|
|
25
|
+
]
|
|
26
|
+
requires-python = ">=3.11"
|
|
27
|
+
dependencies = [
|
|
28
|
+
"requests>=2.28.0",
|
|
29
|
+
"PyGObject>=3.42.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://github.com/Maex-z9/CC_Usage"
|
|
34
|
+
Repository = "https://github.com/Maex-z9/CC_Usage"
|
|
35
|
+
Issues = "https://github.com/Maex-z9/CC_Usage/issues"
|
|
36
|
+
|
|
37
|
+
[project.scripts]
|
|
38
|
+
claude-usage = "src.main:main"
|
|
39
|
+
|
|
40
|
+
[project.gui-scripts]
|
|
41
|
+
claude-usage-gui = "src.main:main"
|
|
42
|
+
|
|
43
|
+
[tool.setuptools.packages.find]
|
|
44
|
+
where = ["."]
|
|
45
|
+
include = ["src*"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# overlay-CC-usage package
|