claude-statuskit 0.3.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_statuskit-0.3.0/.gitignore +31 -0
- claude_statuskit-0.3.0/CHANGELOG.md +79 -0
- claude_statuskit-0.3.0/PKG-INFO +205 -0
- claude_statuskit-0.3.0/README.md +184 -0
- claude_statuskit-0.3.0/pyproject.toml +34 -0
- claude_statuskit-0.3.0/src/statuskit/__init__.py +120 -0
- claude_statuskit-0.3.0/src/statuskit/cli.py +68 -0
- claude_statuskit-0.3.0/src/statuskit/core/__init__.py +1 -0
- claude_statuskit-0.3.0/src/statuskit/core/config.py +73 -0
- claude_statuskit-0.3.0/src/statuskit/core/loader.py +33 -0
- claude_statuskit-0.3.0/src/statuskit/core/models.py +142 -0
- claude_statuskit-0.3.0/src/statuskit/modules/__init__.py +6 -0
- claude_statuskit-0.3.0/src/statuskit/modules/base.py +38 -0
- claude_statuskit-0.3.0/src/statuskit/modules/git.py +380 -0
- claude_statuskit-0.3.0/src/statuskit/modules/model.py +128 -0
- claude_statuskit-0.3.0/src/statuskit/modules/usage_limits.py +485 -0
- claude_statuskit-0.3.0/src/statuskit/setup/__init__.py +1 -0
- claude_statuskit-0.3.0/src/statuskit/setup/commands.py +222 -0
- claude_statuskit-0.3.0/src/statuskit/setup/config.py +28 -0
- claude_statuskit-0.3.0/src/statuskit/setup/gitignore.py +64 -0
- claude_statuskit-0.3.0/src/statuskit/setup/hooks.py +60 -0
- claude_statuskit-0.3.0/src/statuskit/setup/paths.py +32 -0
- claude_statuskit-0.3.0/src/statuskit/setup/ui.py +31 -0
- claude_statuskit-0.3.0/tests/__init__.py +0 -0
- claude_statuskit-0.3.0/tests/conftest.py +95 -0
- claude_statuskit-0.3.0/tests/factories/__init__.py +22 -0
- claude_statuskit-0.3.0/tests/factories/core.py +82 -0
- claude_statuskit-0.3.0/tests/factories/usage_limits.py +21 -0
- claude_statuskit-0.3.0/tests/test_base_module.py +35 -0
- claude_statuskit-0.3.0/tests/test_cli.py +34 -0
- claude_statuskit-0.3.0/tests/test_config.py +148 -0
- claude_statuskit-0.3.0/tests/test_git_integration.py +58 -0
- claude_statuskit-0.3.0/tests/test_git_module.py +779 -0
- claude_statuskit-0.3.0/tests/test_loader.py +70 -0
- claude_statuskit-0.3.0/tests/test_main.py +111 -0
- claude_statuskit-0.3.0/tests/test_model_module.py +206 -0
- claude_statuskit-0.3.0/tests/test_models.py +44 -0
- claude_statuskit-0.3.0/tests/test_setup_commands.py +319 -0
- claude_statuskit-0.3.0/tests/test_setup_config.py +56 -0
- claude_statuskit-0.3.0/tests/test_setup_gitignore.py +124 -0
- claude_statuskit-0.3.0/tests/test_setup_hooks.py +151 -0
- claude_statuskit-0.3.0/tests/test_setup_paths.py +59 -0
- claude_statuskit-0.3.0/tests/test_setup_ui.py +43 -0
- claude_statuskit-0.3.0/tests/test_usage_limits.py +473 -0
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.egg-info/
|
|
6
|
+
dist/
|
|
7
|
+
build/
|
|
8
|
+
|
|
9
|
+
# Virtual environment
|
|
10
|
+
.venv/
|
|
11
|
+
venv/
|
|
12
|
+
|
|
13
|
+
# uv
|
|
14
|
+
uv.lock
|
|
15
|
+
|
|
16
|
+
# pytest
|
|
17
|
+
.pytest_cache/
|
|
18
|
+
|
|
19
|
+
# ruff
|
|
20
|
+
.ruff_cache/
|
|
21
|
+
|
|
22
|
+
# IDE
|
|
23
|
+
.idea/
|
|
24
|
+
.vscode/
|
|
25
|
+
*.swp
|
|
26
|
+
|
|
27
|
+
# macOS
|
|
28
|
+
.DS_Store
|
|
29
|
+
|
|
30
|
+
# Local config (keep template, ignore actual)
|
|
31
|
+
*.local
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.3.0](https://github.com/NoNameItem/claude-tools/compare/statuskit-0.2.1...statuskit-0.3.0) (2026-01-27)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Features
|
|
12
|
+
|
|
13
|
+
* statuskit MVP implementation ([1ce5ea4](https://github.com/NoNameItem/claude-tools/commit/1ce5ea486a55f6470cd7711257d2d5651281cc41))
|
|
14
|
+
* **statuskit:** add CLI interface and setup command ([#2](https://github.com/NoNameItem/claude-tools/issues/2)) ([469ca00](https://github.com/NoNameItem/claude-tools/commit/469ca0022051e37992fb645058daeca075fc7e9f))
|
|
15
|
+
* **statuskit:** add git module ([#26](https://github.com/NoNameItem/claude-tools/issues/26)) ([4fc5615](https://github.com/NoNameItem/claude-tools/commit/4fc56155a8b0db07ae742f07a2e53c5818745aa4))
|
|
16
|
+
* **statuskit:** add usage_limits module ([#27](https://github.com/NoNameItem/claude-tools/issues/27)) ([8c2f6f2](https://github.com/NoNameItem/claude-tools/commit/8c2f6f2d60ab2e121e73f7ba0159ba76776b54e4))
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
### Bug Fixes
|
|
20
|
+
|
|
21
|
+
* **statuskit:** example output ([#30](https://github.com/NoNameItem/claude-tools/issues/30)) ([369fb54](https://github.com/NoNameItem/claude-tools/commit/369fb54bdd0b557b17f77421b57b0d17c40bfffb))
|
|
22
|
+
* **statuskit:** resolve ty type checker warnings ([#4](https://github.com/NoNameItem/claude-tools/issues/4)) ([9207737](https://github.com/NoNameItem/claude-tools/commit/9207737257d75b966506752001d62ec25747939d))
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
### Documentation
|
|
26
|
+
|
|
27
|
+
* **statuskit:** update README for PyPI ([#29](https://github.com/NoNameItem/claude-tools/issues/29)) ([c8af389](https://github.com/NoNameItem/claude-tools/commit/c8af389d92ad9d12e345e2892e94011eeec0f47f))
|
|
28
|
+
|
|
29
|
+
## [0.2.1](https://github.com/NoNameItem/claude-tools/compare/statuskit-0.2.0...statuskit-0.2.1) (2026-01-27)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
### Bug Fixes
|
|
33
|
+
|
|
34
|
+
* **statuskit:** example output ([#30](https://github.com/NoNameItem/claude-tools/issues/30)) ([369fb54](https://github.com/NoNameItem/claude-tools/commit/369fb54bdd0b557b17f77421b57b0d17c40bfffb))
|
|
35
|
+
|
|
36
|
+
## [0.2.0](https://github.com/NoNameItem/claude-tools/compare/statuskit-0.1.0...statuskit-0.2.0) (2026-01-27)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
### Features
|
|
40
|
+
|
|
41
|
+
* statuskit MVP implementation ([1ce5ea4](https://github.com/NoNameItem/claude-tools/commit/1ce5ea486a55f6470cd7711257d2d5651281cc41))
|
|
42
|
+
* **statuskit:** add CLI interface and setup command ([#2](https://github.com/NoNameItem/claude-tools/issues/2)) ([469ca00](https://github.com/NoNameItem/claude-tools/commit/469ca0022051e37992fb645058daeca075fc7e9f))
|
|
43
|
+
* **statuskit:** add git module ([#26](https://github.com/NoNameItem/claude-tools/issues/26)) ([4fc5615](https://github.com/NoNameItem/claude-tools/commit/4fc56155a8b0db07ae742f07a2e53c5818745aa4))
|
|
44
|
+
* **statuskit:** add usage_limits module ([#27](https://github.com/NoNameItem/claude-tools/issues/27)) ([8c2f6f2](https://github.com/NoNameItem/claude-tools/commit/8c2f6f2d60ab2e121e73f7ba0159ba76776b54e4))
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
### Bug Fixes
|
|
48
|
+
|
|
49
|
+
* **statuskit:** resolve ty type checker warnings ([#4](https://github.com/NoNameItem/claude-tools/issues/4)) ([9207737](https://github.com/NoNameItem/claude-tools/commit/9207737257d75b966506752001d62ec25747939d))
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
### Documentation
|
|
53
|
+
|
|
54
|
+
* **statuskit:** update README for PyPI ([#29](https://github.com/NoNameItem/claude-tools/issues/29)) ([c8af389](https://github.com/NoNameItem/claude-tools/commit/c8af389d92ad9d12e345e2892e94011eeec0f47f))
|
|
55
|
+
|
|
56
|
+
## [0.1.0] - 2026-01-19
|
|
57
|
+
|
|
58
|
+
### Added
|
|
59
|
+
|
|
60
|
+
- Modular statusline architecture with plugin system
|
|
61
|
+
- Built-in module `model` displaying:
|
|
62
|
+
- Current Claude model name
|
|
63
|
+
- Session duration (e.g., `2h 15m`)
|
|
64
|
+
- Context window usage with color coding (green/yellow/red)
|
|
65
|
+
- Multiple display formats: `free`, `used`, `ratio`, `bar`
|
|
66
|
+
- Compact number formatting option (e.g., `150k` instead of `150,000`)
|
|
67
|
+
- CLI interface with `--version` and `--help`
|
|
68
|
+
- Setup command for hook installation:
|
|
69
|
+
- `statuskit setup` — interactive installation
|
|
70
|
+
- `statuskit setup --check` — verify installation
|
|
71
|
+
- `statuskit setup --remove` — uninstall hook
|
|
72
|
+
- Hierarchical config loading (global, project, local)
|
|
73
|
+
- Automatic detection of higher-scope installations
|
|
74
|
+
- Backup creation before modifying settings
|
|
75
|
+
- Gitignore handling for local scope configs
|
|
76
|
+
|
|
77
|
+
### Fixed
|
|
78
|
+
|
|
79
|
+
- Type checker warnings resolved
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: claude-statuskit
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Modular statusline for Claude Code
|
|
5
|
+
Project-URL: Homepage, https://github.com/NoNameItem/claude-tools/tree/master/packages/statuskit
|
|
6
|
+
Project-URL: Repository, https://github.com/NoNameItem/claude-tools
|
|
7
|
+
Author-email: Artem Vasin <nonameitem@me.com>
|
|
8
|
+
License: MIT
|
|
9
|
+
Keywords: claude,claude-code,cli,statusline
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Requires-Dist: termcolor
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
# statuskit
|
|
23
|
+
|
|
24
|
+
[](https://pypi.org/project/claude-statuskit/)
|
|
25
|
+
[](https://pypi.org/project/claude-statuskit/)
|
|
26
|
+
[](https://github.com/NoNameItem/claude-tools/blob/master/LICENSE)
|
|
27
|
+
|
|
28
|
+
Modular statusline for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
|
|
29
|
+
|
|
30
|
+
Statuskit displays contextual information below Claude's responses: current model, git status, API usage limits, and more. It reads JSON from Claude Code's statusline hook and renders formatted, colored output.
|
|
31
|
+
|
|
32
|
+
## Features
|
|
33
|
+
|
|
34
|
+
- **Modular architecture** — enable only the modules you need
|
|
35
|
+
- **Configurable** — customize each module's behavior via TOML config
|
|
36
|
+
- **Built-in modules:**
|
|
37
|
+
- `model` — current Claude model name
|
|
38
|
+
- `git` — branch, remote status, changes, last commit, project/worktree location
|
|
39
|
+
- `usage_limits` — API quota tracking (5h session, 7d weekly) with color-coded warnings
|
|
40
|
+
- **Coming soon:**
|
|
41
|
+
- `beads` — display active beads tasks
|
|
42
|
+
- External modules support — load custom modules from separate packages
|
|
43
|
+
|
|
44
|
+
## Installation
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# Using uv (recommended)
|
|
48
|
+
uv tool install claude-statuskit
|
|
49
|
+
|
|
50
|
+
# Using pipx
|
|
51
|
+
pipx install claude-statuskit
|
|
52
|
+
|
|
53
|
+
# Using pip
|
|
54
|
+
pip install claude-statuskit
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Quick Start
|
|
58
|
+
|
|
59
|
+
Run the setup command to configure Claude Code:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
# User-level setup (recommended for personal use)
|
|
63
|
+
statuskit setup
|
|
64
|
+
|
|
65
|
+
# Project-level setup (shared config for team)
|
|
66
|
+
statuskit setup --scope project
|
|
67
|
+
|
|
68
|
+
# Local setup (personal overrides, gitignored)
|
|
69
|
+
statuskit setup --scope local
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Setup will:
|
|
73
|
+
1. Add the statusline hook to Claude Code settings
|
|
74
|
+
2. Create configuration file at the appropriate level
|
|
75
|
+
3. Update gitignore for local configs (if applicable)
|
|
76
|
+
|
|
77
|
+
After setup, restart Claude Code to see the statusline.
|
|
78
|
+
|
|
79
|
+
## Example Output
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
Opus 4.5 · 47m · 120k free (60%)
|
|
83
|
+
claude-tools master ↑1 +2 ~1 ?3 · a1b2c3d 2h
|
|
84
|
+
Session: 45% (2h 30m) · Weekly: 12%
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
This shows:
|
|
88
|
+
- **Line 1 (model):** Model name, session duration, context window
|
|
89
|
+
- **Line 2 (git):** Project, branch, remote status, changes, last commit
|
|
90
|
+
- **Line 3 (usage_limits):** API quota for session and weekly limits
|
|
91
|
+
|
|
92
|
+
## Configuration
|
|
93
|
+
|
|
94
|
+
Configuration files are loaded in priority order (first found wins):
|
|
95
|
+
|
|
96
|
+
| Level | Path | Use case |
|
|
97
|
+
|-------|------|----------|
|
|
98
|
+
| Local | `.claude/statuskit.local.toml` | Personal overrides, gitignored |
|
|
99
|
+
| Project | `.claude/statuskit.toml` | Shared team configuration |
|
|
100
|
+
| User | `~/.claude/statuskit.toml` | Global personal defaults |
|
|
101
|
+
|
|
102
|
+
### Basic Configuration
|
|
103
|
+
|
|
104
|
+
```toml
|
|
105
|
+
# Modules to display (in order)
|
|
106
|
+
modules = ["model", "git", "usage_limits"]
|
|
107
|
+
|
|
108
|
+
# Enable debug output
|
|
109
|
+
debug = false
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Module Configuration
|
|
113
|
+
|
|
114
|
+
Each module can be configured in its own section:
|
|
115
|
+
|
|
116
|
+
```toml
|
|
117
|
+
[git]
|
|
118
|
+
show_branch = true
|
|
119
|
+
commit_age_format = "compact"
|
|
120
|
+
|
|
121
|
+
[usage_limits]
|
|
122
|
+
show_session = true
|
|
123
|
+
show_weekly = true
|
|
124
|
+
multiline = false
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Module Reference
|
|
128
|
+
|
|
129
|
+
### `model` Module
|
|
130
|
+
|
|
131
|
+
Displays model name, session duration, and context window usage.
|
|
132
|
+
|
|
133
|
+
| Parameter | Type | Default | Description |
|
|
134
|
+
|-----------|------|---------|-------------|
|
|
135
|
+
| `show_duration` | bool | `true` | Show session duration |
|
|
136
|
+
| `show_context` | bool | `true` | Show context window usage |
|
|
137
|
+
| `context_format` | string | `"free"` | Context display format (see below) |
|
|
138
|
+
| `context_compact` | bool | `false` | Use compact numbers (e.g., `150k` instead of `150,000`) |
|
|
139
|
+
| `context_threshold_green` | int | `50` | Percentage of free context to show green |
|
|
140
|
+
| `context_threshold_yellow` | int | `25` | Percentage of free context to show yellow (below = red) |
|
|
141
|
+
|
|
142
|
+
**`context_format` values:**
|
|
143
|
+
|
|
144
|
+
| Value | Output example |
|
|
145
|
+
|-------|----------------|
|
|
146
|
+
| `"free"` | `150,000 free (75.0%)` |
|
|
147
|
+
| `"used"` | `50,000 used (25.0%)` |
|
|
148
|
+
| `"ratio"` | `50,000/200,000 (25.0%)` |
|
|
149
|
+
| `"bar"` | `[███████░░░] 70%` |
|
|
150
|
+
|
|
151
|
+
### `git` Module
|
|
152
|
+
|
|
153
|
+
Displays git branch, remote status, changes, last commit, and project/worktree location.
|
|
154
|
+
|
|
155
|
+
| Parameter | Type | Default | Description |
|
|
156
|
+
|-----------|------|---------|-------------|
|
|
157
|
+
| `show_project` | bool | `true` | Show project (repository) name |
|
|
158
|
+
| `show_worktree` | bool | `true` | Show worktree name with 🌲 indicator |
|
|
159
|
+
| `show_folder` | bool | `true` | Show current subfolder relative to repo root |
|
|
160
|
+
| `show_branch` | bool | `true` | Show current branch name |
|
|
161
|
+
| `show_remote_status` | bool | `true` | Show ahead/behind/diverged status |
|
|
162
|
+
| `show_changes` | bool | `true` | Show staged/modified/untracked counts |
|
|
163
|
+
| `show_commit` | bool | `true` | Show last commit hash and age |
|
|
164
|
+
| `commit_age_format` | string | `"relative"` | Commit age format (see below) |
|
|
165
|
+
|
|
166
|
+
**`commit_age_format` values:**
|
|
167
|
+
|
|
168
|
+
| Value | Output example |
|
|
169
|
+
|-------|----------------|
|
|
170
|
+
| `"relative"` | `2 hours ago` |
|
|
171
|
+
| `"compact"` | `2h` |
|
|
172
|
+
|
|
173
|
+
### `usage_limits` Module
|
|
174
|
+
|
|
175
|
+
Displays API usage limits with color-coded warnings based on consumption rate.
|
|
176
|
+
|
|
177
|
+
| Parameter | Type | Default | Description |
|
|
178
|
+
|-----------|------|---------|-------------|
|
|
179
|
+
| `show_session` | bool | `true` | Show 5-hour session limit |
|
|
180
|
+
| `show_weekly` | bool | `true` | Show 7-day weekly limit |
|
|
181
|
+
| `show_sonnet` | bool | `false` | Show Sonnet-only weekly limit |
|
|
182
|
+
| `show_reset_time` | bool | `true` | Show time until reset |
|
|
183
|
+
| `multiline` | bool | `true` | Display each limit on separate line |
|
|
184
|
+
| `show_progress_bar` | bool | `false` | Show visual progress bar |
|
|
185
|
+
| `bar_width` | int | `10` | Progress bar width in characters |
|
|
186
|
+
| `session_time_format` | string | `"remaining"` | Time format for session limit |
|
|
187
|
+
| `weekly_time_format` | string | `"reset_at"` | Time format for weekly limit |
|
|
188
|
+
| `sonnet_time_format` | string | `"reset_at"` | Time format for Sonnet limit |
|
|
189
|
+
| `cache_ttl` | int | `60` | Cache lifetime in seconds |
|
|
190
|
+
|
|
191
|
+
**Time format values:**
|
|
192
|
+
|
|
193
|
+
| Value | Output example |
|
|
194
|
+
|-------|----------------|
|
|
195
|
+
| `"remaining"` | `2h 30m` |
|
|
196
|
+
| `"reset_at"` | `Thu 17:00` |
|
|
197
|
+
|
|
198
|
+
**Color coding:** Usage is colored based on consumption rate vs elapsed time:
|
|
199
|
+
- 🟢 Green — on track or under
|
|
200
|
+
- 🟡 Yellow — approaching the limit trajectory
|
|
201
|
+
- 🔴 Red — ahead of pace, may hit limit
|
|
202
|
+
|
|
203
|
+
## License
|
|
204
|
+
|
|
205
|
+
MIT — see [LICENSE](https://github.com/NoNameItem/claude-tools/blob/master/LICENSE) for details.
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# statuskit
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/claude-statuskit/)
|
|
4
|
+
[](https://pypi.org/project/claude-statuskit/)
|
|
5
|
+
[](https://github.com/NoNameItem/claude-tools/blob/master/LICENSE)
|
|
6
|
+
|
|
7
|
+
Modular statusline for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
|
|
8
|
+
|
|
9
|
+
Statuskit displays contextual information below Claude's responses: current model, git status, API usage limits, and more. It reads JSON from Claude Code's statusline hook and renders formatted, colored output.
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
- **Modular architecture** — enable only the modules you need
|
|
14
|
+
- **Configurable** — customize each module's behavior via TOML config
|
|
15
|
+
- **Built-in modules:**
|
|
16
|
+
- `model` — current Claude model name
|
|
17
|
+
- `git` — branch, remote status, changes, last commit, project/worktree location
|
|
18
|
+
- `usage_limits` — API quota tracking (5h session, 7d weekly) with color-coded warnings
|
|
19
|
+
- **Coming soon:**
|
|
20
|
+
- `beads` — display active beads tasks
|
|
21
|
+
- External modules support — load custom modules from separate packages
|
|
22
|
+
|
|
23
|
+
## Installation
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# Using uv (recommended)
|
|
27
|
+
uv tool install claude-statuskit
|
|
28
|
+
|
|
29
|
+
# Using pipx
|
|
30
|
+
pipx install claude-statuskit
|
|
31
|
+
|
|
32
|
+
# Using pip
|
|
33
|
+
pip install claude-statuskit
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Quick Start
|
|
37
|
+
|
|
38
|
+
Run the setup command to configure Claude Code:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
# User-level setup (recommended for personal use)
|
|
42
|
+
statuskit setup
|
|
43
|
+
|
|
44
|
+
# Project-level setup (shared config for team)
|
|
45
|
+
statuskit setup --scope project
|
|
46
|
+
|
|
47
|
+
# Local setup (personal overrides, gitignored)
|
|
48
|
+
statuskit setup --scope local
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Setup will:
|
|
52
|
+
1. Add the statusline hook to Claude Code settings
|
|
53
|
+
2. Create configuration file at the appropriate level
|
|
54
|
+
3. Update gitignore for local configs (if applicable)
|
|
55
|
+
|
|
56
|
+
After setup, restart Claude Code to see the statusline.
|
|
57
|
+
|
|
58
|
+
## Example Output
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
Opus 4.5 · 47m · 120k free (60%)
|
|
62
|
+
claude-tools master ↑1 +2 ~1 ?3 · a1b2c3d 2h
|
|
63
|
+
Session: 45% (2h 30m) · Weekly: 12%
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
This shows:
|
|
67
|
+
- **Line 1 (model):** Model name, session duration, context window
|
|
68
|
+
- **Line 2 (git):** Project, branch, remote status, changes, last commit
|
|
69
|
+
- **Line 3 (usage_limits):** API quota for session and weekly limits
|
|
70
|
+
|
|
71
|
+
## Configuration
|
|
72
|
+
|
|
73
|
+
Configuration files are loaded in priority order (first found wins):
|
|
74
|
+
|
|
75
|
+
| Level | Path | Use case |
|
|
76
|
+
|-------|------|----------|
|
|
77
|
+
| Local | `.claude/statuskit.local.toml` | Personal overrides, gitignored |
|
|
78
|
+
| Project | `.claude/statuskit.toml` | Shared team configuration |
|
|
79
|
+
| User | `~/.claude/statuskit.toml` | Global personal defaults |
|
|
80
|
+
|
|
81
|
+
### Basic Configuration
|
|
82
|
+
|
|
83
|
+
```toml
|
|
84
|
+
# Modules to display (in order)
|
|
85
|
+
modules = ["model", "git", "usage_limits"]
|
|
86
|
+
|
|
87
|
+
# Enable debug output
|
|
88
|
+
debug = false
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Module Configuration
|
|
92
|
+
|
|
93
|
+
Each module can be configured in its own section:
|
|
94
|
+
|
|
95
|
+
```toml
|
|
96
|
+
[git]
|
|
97
|
+
show_branch = true
|
|
98
|
+
commit_age_format = "compact"
|
|
99
|
+
|
|
100
|
+
[usage_limits]
|
|
101
|
+
show_session = true
|
|
102
|
+
show_weekly = true
|
|
103
|
+
multiline = false
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Module Reference
|
|
107
|
+
|
|
108
|
+
### `model` Module
|
|
109
|
+
|
|
110
|
+
Displays model name, session duration, and context window usage.
|
|
111
|
+
|
|
112
|
+
| Parameter | Type | Default | Description |
|
|
113
|
+
|-----------|------|---------|-------------|
|
|
114
|
+
| `show_duration` | bool | `true` | Show session duration |
|
|
115
|
+
| `show_context` | bool | `true` | Show context window usage |
|
|
116
|
+
| `context_format` | string | `"free"` | Context display format (see below) |
|
|
117
|
+
| `context_compact` | bool | `false` | Use compact numbers (e.g., `150k` instead of `150,000`) |
|
|
118
|
+
| `context_threshold_green` | int | `50` | Percentage of free context to show green |
|
|
119
|
+
| `context_threshold_yellow` | int | `25` | Percentage of free context to show yellow (below = red) |
|
|
120
|
+
|
|
121
|
+
**`context_format` values:**
|
|
122
|
+
|
|
123
|
+
| Value | Output example |
|
|
124
|
+
|-------|----------------|
|
|
125
|
+
| `"free"` | `150,000 free (75.0%)` |
|
|
126
|
+
| `"used"` | `50,000 used (25.0%)` |
|
|
127
|
+
| `"ratio"` | `50,000/200,000 (25.0%)` |
|
|
128
|
+
| `"bar"` | `[███████░░░] 70%` |
|
|
129
|
+
|
|
130
|
+
### `git` Module
|
|
131
|
+
|
|
132
|
+
Displays git branch, remote status, changes, last commit, and project/worktree location.
|
|
133
|
+
|
|
134
|
+
| Parameter | Type | Default | Description |
|
|
135
|
+
|-----------|------|---------|-------------|
|
|
136
|
+
| `show_project` | bool | `true` | Show project (repository) name |
|
|
137
|
+
| `show_worktree` | bool | `true` | Show worktree name with 🌲 indicator |
|
|
138
|
+
| `show_folder` | bool | `true` | Show current subfolder relative to repo root |
|
|
139
|
+
| `show_branch` | bool | `true` | Show current branch name |
|
|
140
|
+
| `show_remote_status` | bool | `true` | Show ahead/behind/diverged status |
|
|
141
|
+
| `show_changes` | bool | `true` | Show staged/modified/untracked counts |
|
|
142
|
+
| `show_commit` | bool | `true` | Show last commit hash and age |
|
|
143
|
+
| `commit_age_format` | string | `"relative"` | Commit age format (see below) |
|
|
144
|
+
|
|
145
|
+
**`commit_age_format` values:**
|
|
146
|
+
|
|
147
|
+
| Value | Output example |
|
|
148
|
+
|-------|----------------|
|
|
149
|
+
| `"relative"` | `2 hours ago` |
|
|
150
|
+
| `"compact"` | `2h` |
|
|
151
|
+
|
|
152
|
+
### `usage_limits` Module
|
|
153
|
+
|
|
154
|
+
Displays API usage limits with color-coded warnings based on consumption rate.
|
|
155
|
+
|
|
156
|
+
| Parameter | Type | Default | Description |
|
|
157
|
+
|-----------|------|---------|-------------|
|
|
158
|
+
| `show_session` | bool | `true` | Show 5-hour session limit |
|
|
159
|
+
| `show_weekly` | bool | `true` | Show 7-day weekly limit |
|
|
160
|
+
| `show_sonnet` | bool | `false` | Show Sonnet-only weekly limit |
|
|
161
|
+
| `show_reset_time` | bool | `true` | Show time until reset |
|
|
162
|
+
| `multiline` | bool | `true` | Display each limit on separate line |
|
|
163
|
+
| `show_progress_bar` | bool | `false` | Show visual progress bar |
|
|
164
|
+
| `bar_width` | int | `10` | Progress bar width in characters |
|
|
165
|
+
| `session_time_format` | string | `"remaining"` | Time format for session limit |
|
|
166
|
+
| `weekly_time_format` | string | `"reset_at"` | Time format for weekly limit |
|
|
167
|
+
| `sonnet_time_format` | string | `"reset_at"` | Time format for Sonnet limit |
|
|
168
|
+
| `cache_ttl` | int | `60` | Cache lifetime in seconds |
|
|
169
|
+
|
|
170
|
+
**Time format values:**
|
|
171
|
+
|
|
172
|
+
| Value | Output example |
|
|
173
|
+
|-------|----------------|
|
|
174
|
+
| `"remaining"` | `2h 30m` |
|
|
175
|
+
| `"reset_at"` | `Thu 17:00` |
|
|
176
|
+
|
|
177
|
+
**Color coding:** Usage is colored based on consumption rate vs elapsed time:
|
|
178
|
+
- 🟢 Green — on track or under
|
|
179
|
+
- 🟡 Yellow — approaching the limit trajectory
|
|
180
|
+
- 🔴 Red — ahead of pace, may hit limit
|
|
181
|
+
|
|
182
|
+
## License
|
|
183
|
+
|
|
184
|
+
MIT — see [LICENSE](https://github.com/NoNameItem/claude-tools/blob/master/LICENSE) for details.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "claude-statuskit"
|
|
3
|
+
version = "0.3.0"
|
|
4
|
+
description = "Modular statusline for Claude Code"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.11"
|
|
7
|
+
license = { text = "MIT" }
|
|
8
|
+
authors = [{ name = "Artem Vasin", email = "nonameitem@me.com" }]
|
|
9
|
+
keywords = ["claude", "claude-code", "statusline", "cli"]
|
|
10
|
+
classifiers = [
|
|
11
|
+
"Development Status :: 3 - Alpha",
|
|
12
|
+
"Environment :: Console",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"License :: OSI Approved :: MIT License",
|
|
15
|
+
"Programming Language :: Python :: 3.11",
|
|
16
|
+
"Programming Language :: Python :: 3.12",
|
|
17
|
+
"Programming Language :: Python :: 3.13",
|
|
18
|
+
"Programming Language :: Python :: 3.14",
|
|
19
|
+
]
|
|
20
|
+
dependencies = ["termcolor"]
|
|
21
|
+
|
|
22
|
+
[project.scripts]
|
|
23
|
+
statuskit = "statuskit:main"
|
|
24
|
+
|
|
25
|
+
[project.urls]
|
|
26
|
+
Homepage = "https://github.com/NoNameItem/claude-tools/tree/master/packages/statuskit"
|
|
27
|
+
Repository = "https://github.com/NoNameItem/claude-tools"
|
|
28
|
+
|
|
29
|
+
[build-system]
|
|
30
|
+
requires = ["hatchling"]
|
|
31
|
+
build-backend = "hatchling.build"
|
|
32
|
+
|
|
33
|
+
[tool.hatch.build.targets.wheel]
|
|
34
|
+
packages = ["src/statuskit"]
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
"""Modular statusline kit for Claude Code."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import sys
|
|
5
|
+
from argparse import Namespace
|
|
6
|
+
|
|
7
|
+
from termcolor import colored
|
|
8
|
+
|
|
9
|
+
from .cli import create_parser
|
|
10
|
+
from .core.config import load_config
|
|
11
|
+
from .core.loader import load_modules
|
|
12
|
+
from .core.models import RenderContext, StatusInput
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _handle_setup(args: Namespace) -> None:
|
|
16
|
+
"""Handle setup command."""
|
|
17
|
+
from .setup.commands import check_installation
|
|
18
|
+
from .setup.paths import Scope
|
|
19
|
+
from .setup.ui import ConsoleUI
|
|
20
|
+
|
|
21
|
+
if args.check:
|
|
22
|
+
print(check_installation())
|
|
23
|
+
return
|
|
24
|
+
|
|
25
|
+
scope = Scope(args.scope)
|
|
26
|
+
ui = None if args.force else ConsoleUI()
|
|
27
|
+
|
|
28
|
+
if args.remove:
|
|
29
|
+
_handle_remove(scope, args.force, ui)
|
|
30
|
+
else:
|
|
31
|
+
_handle_install(scope, args.force, ui)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _handle_remove(scope, force: bool, ui) -> None:
|
|
35
|
+
"""Handle setup --remove command."""
|
|
36
|
+
from .setup.commands import remove_hook
|
|
37
|
+
|
|
38
|
+
result = remove_hook(scope, force=force, ui=ui)
|
|
39
|
+
if result.not_installed:
|
|
40
|
+
print(f"statuskit is not installed at {scope.value} scope.")
|
|
41
|
+
elif result.success:
|
|
42
|
+
print(f"\u2713 Removed statusline hook from {scope.value} scope.")
|
|
43
|
+
else:
|
|
44
|
+
print(f"Error: {result.message}")
|
|
45
|
+
sys.exit(1)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _handle_install(scope, force: bool, ui) -> None:
|
|
49
|
+
"""Handle setup install command."""
|
|
50
|
+
from .setup.commands import install_hook
|
|
51
|
+
|
|
52
|
+
result = install_hook(scope, force=force, ui=ui)
|
|
53
|
+
if result.higher_scope_installed and result.higher_scope:
|
|
54
|
+
print(f"statuskit is already installed at {result.higher_scope.value} scope.")
|
|
55
|
+
print("The hook will work for this project too.")
|
|
56
|
+
if result.config_created:
|
|
57
|
+
print(f"\u2713 Created config file at {scope.value} scope.")
|
|
58
|
+
elif result.already_installed:
|
|
59
|
+
print(f"statuskit is already installed at {scope.value} scope.")
|
|
60
|
+
if result.config_created:
|
|
61
|
+
print("\u2713 Created config file.")
|
|
62
|
+
elif result.success:
|
|
63
|
+
print(f"\u2713 Added statusline hook to {scope.value} scope.")
|
|
64
|
+
if result.backup_created:
|
|
65
|
+
print("\u2713 Created backup of previous settings.")
|
|
66
|
+
if result.config_created:
|
|
67
|
+
print("\u2713 Created config file.")
|
|
68
|
+
if result.gitignore_updated:
|
|
69
|
+
print("\u2713 Added .claude/*.local.* to .gitignore")
|
|
70
|
+
print("\nRun `claude` to see your new statusline!")
|
|
71
|
+
else:
|
|
72
|
+
print(f"Error: {result.message}")
|
|
73
|
+
sys.exit(1)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _render_statusline() -> None:
|
|
77
|
+
"""Read from stdin and render statusline."""
|
|
78
|
+
config = load_config()
|
|
79
|
+
|
|
80
|
+
try:
|
|
81
|
+
raw_data = json.load(sys.stdin)
|
|
82
|
+
data = StatusInput.from_dict(raw_data)
|
|
83
|
+
except Exception as e:
|
|
84
|
+
if config.debug:
|
|
85
|
+
print(colored(f"[!] Failed to parse input: {e}", "red"))
|
|
86
|
+
return
|
|
87
|
+
|
|
88
|
+
ctx = RenderContext(debug=config.debug, data=data, cache_dir=config.cache_dir)
|
|
89
|
+
modules = load_modules(config, ctx)
|
|
90
|
+
|
|
91
|
+
for mod in modules:
|
|
92
|
+
try:
|
|
93
|
+
output = mod.render()
|
|
94
|
+
if output:
|
|
95
|
+
print(output)
|
|
96
|
+
except Exception as e:
|
|
97
|
+
if config.debug:
|
|
98
|
+
print(colored(f"[!] {mod.name}: {e}", "red"))
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def main() -> None:
|
|
102
|
+
"""Entry point for statuskit command."""
|
|
103
|
+
parser = create_parser()
|
|
104
|
+
args = parser.parse_args()
|
|
105
|
+
|
|
106
|
+
if args.command == "setup":
|
|
107
|
+
_handle_setup(args)
|
|
108
|
+
return
|
|
109
|
+
|
|
110
|
+
if sys.stdin.isatty():
|
|
111
|
+
print("statuskit: reads JSON from stdin")
|
|
112
|
+
print("Usage: echo '{...}' | statuskit")
|
|
113
|
+
print("\nRun 'statuskit setup' to configure Claude Code integration.")
|
|
114
|
+
return
|
|
115
|
+
|
|
116
|
+
_render_statusline()
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
if __name__ == "__main__":
|
|
120
|
+
main()
|