Skip to content

Commit 4bd0818

Browse files
neriyaconeriyaco
committed
Initial commit
0 parents  commit 4bd0818

19 files changed

Lines changed: 3406 additions & 0 deletions

File tree

‎.github/workflows/publish.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
8+
jobs:
9+
verify:
10+
runs-on: ubuntu-latest
11+
strategy:
12+
matrix:
13+
python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- name: Set up Python ${{ matrix.python-version }}
18+
uses: actions/setup-python@v5
19+
with:
20+
python-version: ${{ matrix.python-version }}
21+
22+
- name: Install build dependencies
23+
run: |
24+
python -m pip install --upgrade pip
25+
pip install build twine
26+
27+
- name: Build package
28+
run: python -m build
29+
30+
- name: Check package
31+
run: twine check dist/*
32+
33+
publish:
34+
needs: verify
35+
runs-on: ubuntu-latest
36+
environment:
37+
name: pypi
38+
url: https://pypi.org/p/claude-top
39+
permissions:
40+
id-token: write
41+
42+
steps:
43+
- uses: actions/checkout@v4
44+
45+
- name: Set up Python
46+
uses: actions/setup-python@v5
47+
with:
48+
python-version: '3.13'
49+
50+
- name: Install build dependencies
51+
run: |
52+
python -m pip install --upgrade pip
53+
pip install build
54+
55+
- name: Build package
56+
run: python -m build
57+
58+
- name: Publish to PyPI
59+
uses: pypa/gh-action-pypi-publish@release/v1

‎.github/workflows/tests.yml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main, develop ]
8+
9+
jobs:
10+
test:
11+
runs-on: ${{ matrix.os }}
12+
strategy:
13+
matrix:
14+
os: [ubuntu-latest, windows-latest, macos-latest]
15+
python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Set up Python ${{ matrix.python-version }}
21+
uses: actions/setup-python@v5
22+
with:
23+
python-version: ${{ matrix.python-version }}
24+
25+
- name: Install dependencies
26+
run: |
27+
python -m pip install --upgrade pip
28+
pip install -e ".[dev]"
29+
30+
- name: Run tests
31+
run: |
32+
pytest tests/ -v --cov=claude_top --cov-report=term-missing
33+
34+
- name: Upload coverage
35+
if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.14'
36+
uses: codecov/codecov-action@v4
37+
with:
38+
fail_ci_if_error: false
39+
40+
lint:
41+
runs-on: ubuntu-latest
42+
steps:
43+
- uses: actions/checkout@v4
44+
45+
- name: Set up Python
46+
uses: actions/setup-python@v5
47+
with:
48+
python-version: '3.14'
49+
50+
- name: Install dependencies
51+
run: |
52+
python -m pip install --upgrade pip
53+
pip install ruff black
54+
55+
- name: Lint with ruff
56+
run: |
57+
ruff check src/
58+
59+
- name: Check formatting with black
60+
run: |
61+
black --check src/

‎.gitignore‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
build/
8+
develop-eggs/
9+
dist/
10+
downloads/
11+
eggs/
12+
.eggs/
13+
lib/
14+
lib64/
15+
parts/
16+
sdist/
17+
var/
18+
wheels/
19+
*.egg-info/
20+
.installed.cfg
21+
*.egg
22+
23+
# Virtual environments
24+
venv/
25+
env/
26+
ENV/
27+
.venv/
28+
29+
# IDEs
30+
.vscode/
31+
.idea/
32+
*.swp
33+
*.swo
34+
*~
35+
36+
# OS
37+
.DS_Store
38+
Thumbs.db
39+
40+
# Testing
41+
.pytest_cache/
42+
.coverage
43+
htmlcov/
44+
45+
# Build
46+
*.whl
47+
48+
# Local History
49+
.lh/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 claude-top contributors
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.

‎README.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# claude-top
2+
3+
![Claude Top screenshot](images/claude-top.png)
4+
5+
A CLI + TUI utility for inspecting Claude Code usage from local session files.
6+
7+
`claude-top` reads your local Claude history (`~/.claude/projects/**/*.jsonl`), aggregates token/request metrics, and presents them in either:
8+
9+
- an interactive Textual dashboard (default),
10+
- a Rich terminal table (`--no-ui`), or
11+
- JSON (`--json`).
12+
13+
## What it shows
14+
15+
- Total input/output tokens and request count
16+
- Per-model usage breakdown
17+
- Optional detailed stats (`--detailed`):
18+
- cache reads/writes and hit rate
19+
- average tokens per request
20+
- estimated cost (informational)
21+
- 7-day trend sparkline
22+
- week-over-week comparison
23+
- top projects by token usage
24+
- Tier-aware usage bars and warnings (80%/90%) when tier metadata is available
25+
26+
## Requirements
27+
28+
- Python 3.9+
29+
- Existing Claude Code data in `~/.claude/projects`
30+
31+
Notes:
32+
- No setup is required to read local usage files.
33+
- If `~/.claude/.credentials.json` is present with a valid OAuth token, `claude-top` also tries to fetch usage window reset metadata from Anthropic OAuth usage API for better countdowns.
34+
35+
## Installation
36+
37+
### Run without install (uvx)
38+
39+
```bash
40+
uvx claude-top
41+
```
42+
43+
### Install globally (uv)
44+
45+
```bash
46+
uv tool install claude-top
47+
```
48+
49+
### Install with pip
50+
51+
```bash
52+
pip install claude-top
53+
```
54+
55+
### From source
56+
57+
```bash
58+
git clone https://github.com/xpodev/claude-top.git
59+
cd claude-top
60+
uv pip install -e .
61+
```
62+
63+
## Usage
64+
65+
```bash
66+
# Launch TUI (auto-refresh by default)
67+
claude-top
68+
69+
# Print terminal table once and exit
70+
claude-top --no-ui --once
71+
72+
# Print terminal table with refresh
73+
claude-top --no-ui --watch 5
74+
75+
# Print JSON once and exit
76+
claude-top --json
77+
78+
# Include detailed analytics
79+
claude-top --detailed
80+
```
81+
82+
### CLI options
83+
84+
- `--once`: Display once and exit.
85+
- `--no-ui`: Use table output instead of the TUI.
86+
- `--json`: Print JSON output and exit.
87+
- `--detailed`: Include detailed analytics.
88+
- `--watch N`: Refresh interval in seconds (default: 1 when not using `--once`).
89+
90+
### TUI keybindings
91+
92+
- `r`: Refresh now
93+
- `q`: Quit
94+
95+
## How data is calculated
96+
97+
- Scans all JSONL events in `~/.claude/projects` recursively.
98+
- Counts each `assistant` event as one request.
99+
- Aggregates token fields from each assistant message usage payload:
100+
- `input_tokens`
101+
- `output_tokens`
102+
- `cache_creation_input_tokens`
103+
- `cache_read_input_tokens`
104+
- Derives project names from common event path/project fields.
105+
- Builds last-7-day trend and week-over-week token comparison from timestamps.
106+
107+
## Troubleshooting
108+
109+
### "No Claude Code session data found"
110+
111+
`claude-top` only reads local Claude session files. Make sure:
112+
113+
1. Claude Code has been used on this machine.
114+
2. `~/.claude/projects` exists and contains `.jsonl` files.
115+
116+
### Tier/reset countdown is missing
117+
118+
Tier and reset countdown information depends on OAuth metadata. If unavailable:
119+
120+
- ensure `~/.claude/.credentials.json` exists,
121+
- ensure the OAuth token is valid,
122+
- check network access to Anthropic API.
123+
124+
The tool still works with local usage data even if tier/reset metadata cannot be fetched.
125+
126+
## Development
127+
128+
```bash
129+
# Clone repository
130+
git clone https://github.com/xpodev/claude-top.git
131+
cd claude-top
132+
133+
# Install with development dependencies
134+
uv pip install -e ".[dev]"
135+
136+
# Run tests
137+
uv run pytest -q
138+
```
139+
140+
## License
141+
142+
MIT

‎images/claude-top.png‎

57 KB
Loading

0 commit comments

Comments
 (0)