claude-agents-top 0.2.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.
Files changed (12) hide show
  1. claude_agents_top-0.2.0/LICENSE +21 -0
  2. claude_agents_top-0.2.0/PKG-INFO +107 -0
  3. claude_agents_top-0.2.0/README.md +81 -0
  4. claude_agents_top-0.2.0/claude_agents_top.egg-info/PKG-INFO +107 -0
  5. claude_agents_top-0.2.0/claude_agents_top.egg-info/SOURCES.txt +10 -0
  6. claude_agents_top-0.2.0/claude_agents_top.egg-info/dependency_links.txt +1 -0
  7. claude_agents_top-0.2.0/claude_agents_top.egg-info/entry_points.txt +2 -0
  8. claude_agents_top-0.2.0/claude_agents_top.egg-info/top_level.txt +1 -0
  9. claude_agents_top-0.2.0/claude_top.py +1137 -0
  10. claude_agents_top-0.2.0/pyproject.toml +42 -0
  11. claude_agents_top-0.2.0/setup.cfg +4 -0
  12. claude_agents_top-0.2.0/tests/test_claude_top.py +660 -0
claude_agents_top-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jonathan Achai
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.
claude_agents_top-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,107 @@
1
+ Metadata-Version: 2.4
2
+ Name: claude-agents-top
3
+ Version: 0.2.0
4
+ Summary: A top-style live view of your Claude Code background sessions and plan usage
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://github.com/jachai/claude-top
7
+ Project-URL: Issues, https://github.com/jachai/claude-top/issues
8
+ Project-URL: Changelog, https://github.com/jachai/claude-top/blob/main/CHANGELOG.md
9
+ Keywords: claude,claude-code,top,tui,monitor
10
+ Classifier: Environment :: Console :: Curses
11
+ Classifier: Operating System :: MacOS
12
+ Classifier: Operating System :: POSIX :: Linux
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: System :: Monitoring
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: license-file
26
+
27
+ # claude-top
28
+
29
+ `top` for your Claude Code sessions: what each one is doing, what it's waiting on, and how fast you're using your plan.
30
+
31
+ [![test](https://github.com/jachai/claude-top/actions/workflows/test.yml/badge.svg)](https://github.com/jachai/claude-top/actions/workflows/test.yml)
32
+ [![PyPI](https://img.shields.io/pypi/v/claude-agents-top)](https://pypi.org/project/claude-agents-top/)
33
+ [![Python](https://img.shields.io/pypi/pyversions/claude-agents-top)](https://pypi.org/project/claude-agents-top/)
34
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/jachai/claude-top/blob/main/LICENSE)
35
+
36
+ ![claude-top demo](https://raw.githubusercontent.com/jachai/claude-top/main/docs/demo.gif)
37
+
38
+ It's a live view of every background session showing when it was last active, what it's waiting on, its model, effort and context size, and the helpers it started. The header shows your 5-hour and weekly plan usage, how fast you're using it, and when you'd run out.
39
+
40
+ ## Install
41
+
42
+ ```sh
43
+ uv tool install claude-agents-top # or: pipx install claude-agents-top
44
+ uv tool install git+https://github.com/jachai/claude-top # the latest from main
45
+ ```
46
+
47
+ The package is `claude-agents-top` on PyPI because `claude-top` there is an unrelated project. Both install a `claude-top` command, so don't install both. This one is a single file with no dependencies: Python 3.9+ on macOS or Linux (on Windows only `--once` works). You can also copy `claude_top.py` anywhere on your `PATH`.
48
+
49
+ ## Show plan usage (optional)
50
+
51
+ Claude Code hands your plan limits to its status-line command, so claude-top needs to be that command to see them:
52
+
53
+ ```sh
54
+ claude-top init # sets the status line in ~/.claude/settings.json (backs it up first)
55
+ claude-top init --wrap # already have a status line? keep it: record the limits, then run yours
56
+ ```
57
+
58
+ Your status line then shows a line like `5h 38% 0.6x · week 54% 1.3x ▶ out Fri 13:37` (with `--wrap`, your own line, unchanged). `--dry-run` shows the change, `--undo` puts things back. If you'd rather edit your own script, add `echo "$input" | claude-top record` to it.
59
+
60
+ ## Use
61
+
62
+ ```sh
63
+ claude-top # full screen, refreshes every 2s
64
+ claude-top -s waiting # only sessions waiting for you (Claude Code calls it "blocked"; -s blocked works too)
65
+ claude-top -g billing # text filter
66
+ claude-top --once # print once and exit
67
+ ```
68
+
69
+ | Key | Action |
70
+ |---|---|
71
+ | `↑` `↓` / `j` `k` | move |
72
+ | `enter` | open the session (`claude attach <id>`) |
73
+ | `c` | copy the attach command |
74
+ | `o` | sort: last active, created, context, agents, name |
75
+ | `f` | filter by state |
76
+ | `/` | text filter |
77
+ | `+` `-` | refresh slower / faster |
78
+ | `?` | help: every key and column |
79
+ | `q` | quit |
80
+
81
+ ## Reading it
82
+
83
+ - **Header**: sessions by state (`work`ing, `wait`ing for you, `review` = finished in a worktree that's still open, `done`, `stop`ped), then what's running now: working sessions + subagents, subagents spawned in total, and background tasks.
84
+ - **Usage bars (5h, week)**: the bar fills with the % of the limit used, and `│` marks how much of the window (`time`) has passed. A bar filled past the `│` means you're ahead of budget.
85
+ - **Speed (`1.3x`)**: % used ÷ % of time elapsed. `1.0x` lands exactly on 100% at reset, and `2.0x` runs out halfway through. The gauge's middle line is 1x. **now** is the speed over the last few hours (`--rate-hours`, default 3; the week uses a little more because limits come in whole percents).
86
+ - **▶**: when you'll run out at the current speed (and how early that is), or roughly where you'll end up at reset.
87
+ - **LAST ACTIVE / AGE**: last activity vs. when the session was created. The built-in agents view only shows age.
88
+ - **RUN / SPAWNED**: subagents running now / started in total. **BG**: background shells, monitors and crons in flight.
89
+ - **CTX %**: context used, measured against a 1M window. Change it with `-w 200000` or `CLAUDE_TOP_CONTEXT_WINDOW`.
90
+
91
+ ![claude-top screenshot](https://raw.githubusercontent.com/jachai/claude-top/main/docs/screenshot.png)
92
+
93
+ ## Try it without your data
94
+
95
+ ```sh
96
+ python3 scripts/demo.py # made-up sessions in a temp dir
97
+ ```
98
+
99
+ `CLAUDE_CONFIG_DIR` and `CLAUDE_TOP_RATE_LIMITS` override where it reads from; `CLAUDE_TOP_LIVE=0` skips `claude agents`. Running the tests and regenerating the images is covered in [CONTRIBUTING.md](CONTRIBUTING.md), and changes are listed in [CHANGELOG.md](CHANGELOG.md).
100
+
101
+ ## Notes
102
+
103
+ - Session states and names come from `claude agents --json`, the same source as the built-in view. Everything else comes from Claude Code's local files (`~/.claude/jobs`, `~/.claude/projects`). They aren't a public API, so a Claude Code update can break a column; please [open an issue](https://github.com/jachai/claude-top/issues/new/choose) if it does.
104
+ - It only reads, except for its own files in `~/.claude/claude-top/` and, with `init`, the `statusLine` entry of `~/.claude/settings.json`. Nothing leaves your machine.
105
+ - This is an independent project, not affiliated with Anthropic.
106
+
107
+ MIT licensed.
claude_agents_top-0.2.0/README.md ADDED
@@ -0,0 +1,81 @@
1
+ # claude-top
2
+
3
+ `top` for your Claude Code sessions: what each one is doing, what it's waiting on, and how fast you're using your plan.
4
+
5
+ [![test](https://github.com/jachai/claude-top/actions/workflows/test.yml/badge.svg)](https://github.com/jachai/claude-top/actions/workflows/test.yml)
6
+ [![PyPI](https://img.shields.io/pypi/v/claude-agents-top)](https://pypi.org/project/claude-agents-top/)
7
+ [![Python](https://img.shields.io/pypi/pyversions/claude-agents-top)](https://pypi.org/project/claude-agents-top/)
8
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/jachai/claude-top/blob/main/LICENSE)
9
+
10
+ ![claude-top demo](https://raw.githubusercontent.com/jachai/claude-top/main/docs/demo.gif)
11
+
12
+ It's a live view of every background session showing when it was last active, what it's waiting on, its model, effort and context size, and the helpers it started. The header shows your 5-hour and weekly plan usage, how fast you're using it, and when you'd run out.
13
+
14
+ ## Install
15
+
16
+ ```sh
17
+ uv tool install claude-agents-top # or: pipx install claude-agents-top
18
+ uv tool install git+https://github.com/jachai/claude-top # the latest from main
19
+ ```
20
+
21
+ The package is `claude-agents-top` on PyPI because `claude-top` there is an unrelated project. Both install a `claude-top` command, so don't install both. This one is a single file with no dependencies: Python 3.9+ on macOS or Linux (on Windows only `--once` works). You can also copy `claude_top.py` anywhere on your `PATH`.
22
+
23
+ ## Show plan usage (optional)
24
+
25
+ Claude Code hands your plan limits to its status-line command, so claude-top needs to be that command to see them:
26
+
27
+ ```sh
28
+ claude-top init # sets the status line in ~/.claude/settings.json (backs it up first)
29
+ claude-top init --wrap # already have a status line? keep it: record the limits, then run yours
30
+ ```
31
+
32
+ Your status line then shows a line like `5h 38% 0.6x · week 54% 1.3x ▶ out Fri 13:37` (with `--wrap`, your own line, unchanged). `--dry-run` shows the change, `--undo` puts things back. If you'd rather edit your own script, add `echo "$input" | claude-top record` to it.
33
+
34
+ ## Use
35
+
36
+ ```sh
37
+ claude-top # full screen, refreshes every 2s
38
+ claude-top -s waiting # only sessions waiting for you (Claude Code calls it "blocked"; -s blocked works too)
39
+ claude-top -g billing # text filter
40
+ claude-top --once # print once and exit
41
+ ```
42
+
43
+ | Key | Action |
44
+ |---|---|
45
+ | `↑` `↓` / `j` `k` | move |
46
+ | `enter` | open the session (`claude attach <id>`) |
47
+ | `c` | copy the attach command |
48
+ | `o` | sort: last active, created, context, agents, name |
49
+ | `f` | filter by state |
50
+ | `/` | text filter |
51
+ | `+` `-` | refresh slower / faster |
52
+ | `?` | help: every key and column |
53
+ | `q` | quit |
54
+
55
+ ## Reading it
56
+
57
+ - **Header**: sessions by state (`work`ing, `wait`ing for you, `review` = finished in a worktree that's still open, `done`, `stop`ped), then what's running now: working sessions + subagents, subagents spawned in total, and background tasks.
58
+ - **Usage bars (5h, week)**: the bar fills with the % of the limit used, and `│` marks how much of the window (`time`) has passed. A bar filled past the `│` means you're ahead of budget.
59
+ - **Speed (`1.3x`)**: % used ÷ % of time elapsed. `1.0x` lands exactly on 100% at reset, and `2.0x` runs out halfway through. The gauge's middle line is 1x. **now** is the speed over the last few hours (`--rate-hours`, default 3; the week uses a little more because limits come in whole percents).
60
+ - **▶**: when you'll run out at the current speed (and how early that is), or roughly where you'll end up at reset.
61
+ - **LAST ACTIVE / AGE**: last activity vs. when the session was created. The built-in agents view only shows age.
62
+ - **RUN / SPAWNED**: subagents running now / started in total. **BG**: background shells, monitors and crons in flight.
63
+ - **CTX %**: context used, measured against a 1M window. Change it with `-w 200000` or `CLAUDE_TOP_CONTEXT_WINDOW`.
64
+
65
+ ![claude-top screenshot](https://raw.githubusercontent.com/jachai/claude-top/main/docs/screenshot.png)
66
+
67
+ ## Try it without your data
68
+
69
+ ```sh
70
+ python3 scripts/demo.py # made-up sessions in a temp dir
71
+ ```
72
+
73
+ `CLAUDE_CONFIG_DIR` and `CLAUDE_TOP_RATE_LIMITS` override where it reads from; `CLAUDE_TOP_LIVE=0` skips `claude agents`. Running the tests and regenerating the images is covered in [CONTRIBUTING.md](CONTRIBUTING.md), and changes are listed in [CHANGELOG.md](CHANGELOG.md).
74
+
75
+ ## Notes
76
+
77
+ - Session states and names come from `claude agents --json`, the same source as the built-in view. Everything else comes from Claude Code's local files (`~/.claude/jobs`, `~/.claude/projects`). They aren't a public API, so a Claude Code update can break a column; please [open an issue](https://github.com/jachai/claude-top/issues/new/choose) if it does.
78
+ - It only reads, except for its own files in `~/.claude/claude-top/` and, with `init`, the `statusLine` entry of `~/.claude/settings.json`. Nothing leaves your machine.
79
+ - This is an independent project, not affiliated with Anthropic.
80
+
81
+ MIT licensed.
claude_agents_top-0.2.0/claude_agents_top.egg-info/PKG-INFO ADDED
@@ -0,0 +1,107 @@
1
+ Metadata-Version: 2.4
2
+ Name: claude-agents-top
3
+ Version: 0.2.0
4
+ Summary: A top-style live view of your Claude Code background sessions and plan usage
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://github.com/jachai/claude-top
7
+ Project-URL: Issues, https://github.com/jachai/claude-top/issues
8
+ Project-URL: Changelog, https://github.com/jachai/claude-top/blob/main/CHANGELOG.md
9
+ Keywords: claude,claude-code,top,tui,monitor
10
+ Classifier: Environment :: Console :: Curses
11
+ Classifier: Operating System :: MacOS
12
+ Classifier: Operating System :: POSIX :: Linux
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: System :: Monitoring
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: license-file
26
+
27
+ # claude-top
28
+
29
+ `top` for your Claude Code sessions: what each one is doing, what it's waiting on, and how fast you're using your plan.
30
+
31
+ [![test](https://github.com/jachai/claude-top/actions/workflows/test.yml/badge.svg)](https://github.com/jachai/claude-top/actions/workflows/test.yml)
32
+ [![PyPI](https://img.shields.io/pypi/v/claude-agents-top)](https://pypi.org/project/claude-agents-top/)
33
+ [![Python](https://img.shields.io/pypi/pyversions/claude-agents-top)](https://pypi.org/project/claude-agents-top/)
34
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/jachai/claude-top/blob/main/LICENSE)
35
+
36
+ ![claude-top demo](https://raw.githubusercontent.com/jachai/claude-top/main/docs/demo.gif)
37
+
38
+ It's a live view of every background session showing when it was last active, what it's waiting on, its model, effort and context size, and the helpers it started. The header shows your 5-hour and weekly plan usage, how fast you're using it, and when you'd run out.
39
+
40
+ ## Install
41
+
42
+ ```sh
43
+ uv tool install claude-agents-top # or: pipx install claude-agents-top
44
+ uv tool install git+https://github.com/jachai/claude-top # the latest from main
45
+ ```
46
+
47
+ The package is `claude-agents-top` on PyPI because `claude-top` there is an unrelated project. Both install a `claude-top` command, so don't install both. This one is a single file with no dependencies: Python 3.9+ on macOS or Linux (on Windows only `--once` works). You can also copy `claude_top.py` anywhere on your `PATH`.
48
+
49
+ ## Show plan usage (optional)
50
+
51
+ Claude Code hands your plan limits to its status-line command, so claude-top needs to be that command to see them:
52
+
53
+ ```sh
54
+ claude-top init # sets the status line in ~/.claude/settings.json (backs it up first)
55
+ claude-top init --wrap # already have a status line? keep it: record the limits, then run yours
56
+ ```
57
+
58
+ Your status line then shows a line like `5h 38% 0.6x · week 54% 1.3x ▶ out Fri 13:37` (with `--wrap`, your own line, unchanged). `--dry-run` shows the change, `--undo` puts things back. If you'd rather edit your own script, add `echo "$input" | claude-top record` to it.
59
+
60
+ ## Use
61
+
62
+ ```sh
63
+ claude-top # full screen, refreshes every 2s
64
+ claude-top -s waiting # only sessions waiting for you (Claude Code calls it "blocked"; -s blocked works too)
65
+ claude-top -g billing # text filter
66
+ claude-top --once # print once and exit
67
+ ```
68
+
69
+ | Key | Action |
70
+ |---|---|
71
+ | `↑` `↓` / `j` `k` | move |
72
+ | `enter` | open the session (`claude attach <id>`) |
73
+ | `c` | copy the attach command |
74
+ | `o` | sort: last active, created, context, agents, name |
75
+ | `f` | filter by state |
76
+ | `/` | text filter |
77
+ | `+` `-` | refresh slower / faster |
78
+ | `?` | help: every key and column |
79
+ | `q` | quit |
80
+
81
+ ## Reading it
82
+
83
+ - **Header**: sessions by state (`work`ing, `wait`ing for you, `review` = finished in a worktree that's still open, `done`, `stop`ped), then what's running now: working sessions + subagents, subagents spawned in total, and background tasks.
84
+ - **Usage bars (5h, week)**: the bar fills with the % of the limit used, and `│` marks how much of the window (`time`) has passed. A bar filled past the `│` means you're ahead of budget.
85
+ - **Speed (`1.3x`)**: % used ÷ % of time elapsed. `1.0x` lands exactly on 100% at reset, and `2.0x` runs out halfway through. The gauge's middle line is 1x. **now** is the speed over the last few hours (`--rate-hours`, default 3; the week uses a little more because limits come in whole percents).
86
+ - **▶**: when you'll run out at the current speed (and how early that is), or roughly where you'll end up at reset.
87
+ - **LAST ACTIVE / AGE**: last activity vs. when the session was created. The built-in agents view only shows age.
88
+ - **RUN / SPAWNED**: subagents running now / started in total. **BG**: background shells, monitors and crons in flight.
89
+ - **CTX %**: context used, measured against a 1M window. Change it with `-w 200000` or `CLAUDE_TOP_CONTEXT_WINDOW`.
90
+
91
+ ![claude-top screenshot](https://raw.githubusercontent.com/jachai/claude-top/main/docs/screenshot.png)
92
+
93
+ ## Try it without your data
94
+
95
+ ```sh
96
+ python3 scripts/demo.py # made-up sessions in a temp dir
97
+ ```
98
+
99
+ `CLAUDE_CONFIG_DIR` and `CLAUDE_TOP_RATE_LIMITS` override where it reads from; `CLAUDE_TOP_LIVE=0` skips `claude agents`. Running the tests and regenerating the images is covered in [CONTRIBUTING.md](CONTRIBUTING.md), and changes are listed in [CHANGELOG.md](CHANGELOG.md).
100
+
101
+ ## Notes
102
+
103
+ - Session states and names come from `claude agents --json`, the same source as the built-in view. Everything else comes from Claude Code's local files (`~/.claude/jobs`, `~/.claude/projects`). They aren't a public API, so a Claude Code update can break a column; please [open an issue](https://github.com/jachai/claude-top/issues/new/choose) if it does.
104
+ - It only reads, except for its own files in `~/.claude/claude-top/` and, with `init`, the `statusLine` entry of `~/.claude/settings.json`. Nothing leaves your machine.
105
+ - This is an independent project, not affiliated with Anthropic.
106
+
107
+ MIT licensed.
claude_agents_top-0.2.0/claude_agents_top.egg-info/SOURCES.txt ADDED
@@ -0,0 +1,10 @@
1
+ LICENSE
2
+ README.md
3
+ claude_top.py
4
+ pyproject.toml
5
+ claude_agents_top.egg-info/PKG-INFO
6
+ claude_agents_top.egg-info/SOURCES.txt
7
+ claude_agents_top.egg-info/dependency_links.txt
8
+ claude_agents_top.egg-info/entry_points.txt
9
+ claude_agents_top.egg-info/top_level.txt
10
+ tests/test_claude_top.py
claude_agents_top-0.2.0/claude_agents_top.egg-info/entry_points.txt ADDED
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ claude-top = claude_top:main