@mkhuda/agent-ps 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.3.0
+
+The detail panel earns its screen.
+
+- It is grouped now, in the order the questions arrive: what the session is,
+  what it is doing to the machine, what it has cost, and the command line last.
+  The agent name takes its colour from the table, a busy status is green, and an
+  inferred pairing reads as a warning rather than another grey line.
+- The disk total is broken down. A hundred megabytes of transcript and a hundred
+  of file history call for different answers, and the column alone could not
+  tell you which you had. Every backend names its own parts, including the two
+  that keep sessions in a database and count rows rather than files.
+- The panel keeps up. It redrew on every pass and so looked live, but it held
+  the row it was opened with, which left cpu, memory, uptime and the time since
+  the last turn frozen at the moment it appeared.
+
+## 0.2.0
+
+Ways to install it, and a release that publishes itself.
+
+- `curl | sh` takes the latest release, checks it against the checksum
+  published beside it, and makes sure it runs before keeping it.
+- On PyPI as `agent-ps`, so `uvx agent-ps`, `pipx install agent-ps` and
+  `pip install agent-ps` all work.
+- On npm as `@mkhuda/agent-ps`, scoped because the plain name is too close to
+  an existing package. The command it installs is still `agent-ps`.
+- Releases are built and published from the tag on a clean runner, which
+  refuses to start when the tag, the version in the package and this file
+  disagree.
+
+The tool itself is unchanged.
+
 ## 0.1.0
 
 First public release.

package/README.md

@@ -1,15 +1,29 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/mkhuda/agent-ps/main/images/agent-ps-screenshot.jpg" width="900"
+     alt="agent-ps listing sessions from claude, hermes, codex, opencode, pi, commandcode and copilot side by side, each with its model, uptime, idle time, cpu, memory, disk and working directory, with two hermes background helpers at the bottom">
+
 # agent-ps
 
-A process table for coding agent sessions, the way `ps` would look if it knew
-what a session was.
+**A process table for coding agent sessions, the way `ps` would look if it knew
+what a session was.**
+
+[![ci](https://img.shields.io/github/actions/workflow/status/mkhuda/agent-ps/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/mkhuda/agent-ps/actions/workflows/ci.yml)
+[![pypi](https://img.shields.io/pypi/v/agent-ps?style=flat-square&color=blue)](https://pypi.org/project/agent-ps/)
+[![npm](https://img.shields.io/npm/v/%40mkhuda%2Fagent-ps?style=flat-square&color=blue&label=npm)](https://www.npmjs.com/package/@mkhuda/agent-ps)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/mkhuda/agent-ps/blob/main/LICENSE)
+![python](https://img.shields.io/badge/python-3.8%2B-blue?style=flat-square)
+![agents](https://img.shields.io/badge/agents-7-orange?style=flat-square)
+![dependencies](https://img.shields.io/badge/dependencies-none-brightgreen?style=flat-square)
+
+[Install](#install) | [Usage](#usage) | [Agents](#agents) |
+[Scripting](#scripting) | [How it works](https://github.com/mkhuda/agent-ps/blob/main/docs/internals.md)
 
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
-![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue?style=flat-square)
-![macOS and Linux](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey?style=flat-square)
-![No dependencies](https://img.shields.io/badge/dependencies-none-brightgreen?style=flat-square)
-![7 agents](https://img.shields.io/badge/agents-7-orange?style=flat-square)
+```
+curl -fsSL https://raw.githubusercontent.com/mkhuda/agent-ps/main/install.sh | sh
+```
 
-![agent-ps listing sessions from claude, hermes, codex, opencode, pi, commandcode and copilot side by side, each with its model, uptime, idle time, cpu, memory, disk and working directory, with two hermes background helpers at the bottom](images/agent-ps-screenshot.jpg)
+</div>
 
 `ps aux | grep claude` gives you PIDs. It will not tell you which one is the
 session you are talking to, what model it is spending on, whether it has been
@@ -24,16 +38,43 @@ One file, no dependencies, reads local files only.
 
 ## Install
 
+### One command
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/mkhuda/agent-ps/main/install.sh | sh
 ```
 
-That takes the latest release, checks it against the checksum published with it,
-makes sure it runs, and drops the single file into `~/.local/bin`. Set `BIN_DIR`
-to put it elsewhere, or `AGENT_PS_REF=v0.1.0` to pin a version.
+Takes the latest release, checks it against the checksum published beside it,
+makes sure it runs, and puts the single file in `~/.local/bin`. Set `BIN_DIR` to
+install elsewhere, or `AGENT_PS_REF=v0.1.0` to pin a version.
+
+### With a package runner
+
+From [PyPI](https://pypi.org/project/agent-ps/), which installs the program
+itself:
+
+```bash
+uvx agent-ps                  # run it once
+pipx install agent-ps         # keep it, isolated
+pip install agent-ps          # keep it, wherever pip points
+```
+
+From [npm](https://www.npmjs.com/package/@mkhuda/agent-ps), which carries the
+same single executable and finds an interpreter for it:
+
+```bash
+npx @mkhuda/agent-ps
+pnpm dlx @mkhuda/agent-ps
+bunx @mkhuda/agent-ps
+```
+
+The npm package is scoped because the plain name is too close to an existing
+one. Either way the command it gives you is `agent-ps`.
+
+### Just the file
 
 If you would rather not pipe a script into a shell, the executable is the whole
-program and you can fetch it yourself:
+program:
 
 ```bash
 mkdir -p ~/.local/bin
@@ -43,27 +84,31 @@ chmod +x ~/.local/bin/agent-ps
 ```
 
 Every [release](https://github.com/mkhuda/agent-ps/releases) publishes a
-`SHA256SUMS` beside the executable.
+`SHA256SUMS` next to it.
 
-If you install your coding agents with npm, `npx agent-ps` works too. It is the
-same Python program either way; the package only finds an interpreter.
+### From a clone
 
-From a clone, `./install.sh` builds from the tree instead of downloading, so you
-install what you are looking at.
+```bash
+git clone https://github.com/mkhuda/agent-ps && cd agent-ps
+./install.sh
+```
+
+Builds from the tree rather than downloading, so you install what you are
+looking at.
 
-Requires Python 3.8 or later and nothing from PyPI. Tested on 3.8, 3.9, 3.10 and
-3.14. macOS and Linux; Windows is out because `curses` is not in its standard
-library. It shells out to `ps`, and on macOS to `lsof`, which is how a process is
-matched to a session everywhere except Claude Code.
+### What it needs, and how to remove it
 
-To remove it:
+Python 3.8 or later and nothing from PyPI. Tested on 3.8, 3.9, 3.10 and 3.14.
+macOS and Linux; Windows is out because `curses` is not in its standard library.
+It shells out to `ps`, and on macOS to `lsof`, which is how a process is matched
+to a session everywhere except Claude Code.
 
 ```bash
 rm -f ~/.local/bin/agent-ps
 ```
 
-Nothing is written outside that directory. agent-ps only ever reads the agents'
-own files.
+That is the whole uninstall. Nothing is written outside that directory, and
+agent-ps only ever reads the agents' own files.
 
 ## Agents
 
@@ -123,7 +168,7 @@ something.
 Those keys live at the bottom of the screen, under a line naming every agent on
 screen in its own colour and, on the right, what the table is sorted by:
 
-![The bottom of the screen: a legend naming each agent in its own colour, the sort shown in words on the right, and the key bar beneath it](images/agent-ps-footer-screenshot.jpg)
+![The bottom of the screen: a legend naming each agent in its own colour, the sort shown in words on the right, and the key bar beneath it](https://raw.githubusercontent.com/mkhuda/agent-ps/main/images/agent-ps-footer-screenshot.jpg)
 
 That middle line does three jobs. It is the key to the colours in the AGENT
 column, it says the sort order in words so the marked heading is never a guess,
@@ -158,32 +203,31 @@ ended sessions, then `s` until DISK is marked.
 
 ### The detail panel
 
-Enter on a live session opens everything known about it, including tokens and
-cost where the agent counts them:
+Enter on a live session opens everything known about it, grouped in the order
+the questions arrive: what the session is, what it is doing to the machine, what
+it has cost, and the command line last, since it is long and rarely the
+question.
+
+<img src="https://raw.githubusercontent.com/mkhuda/agent-ps/main/images/agent-ps-detail.jpg" width="620"
+     alt="The detail panel for a Claude Code session, in four groups. Session: agent, id, status, model, title and directory. Process: pid with its parent, uptime, and time since the last turn. Usage: cpu, memory, and a 41M disk total broken into 28M of transcript, 11M of subagent logs and 2M of file history. Command: the command line that started it.">
+
+The disk total is broken down, because the number on its own is not something
+you can act on. Forty megabytes of transcript and forty of file history call for
+different answers, and until you can see which it is there is nothing to decide.
+
+Where the agent counts tokens, they are here too. Hermes and OpenCode report
+cost, Copilot reports the credits a turn spent:
 
 ```
- session details
-
-       agent  hermes
-     session  20260905_005254_2c9f4d
-      status  idle
-       model  nemotron-3.5-lightning-free
-   directory  /Users/rg/projects/agent-ps
-       title  halo are you hermes?
-         pid  21098  (parent 17518)
-      uptime  1h17m   last turn 1h15m ago
-       usage  cpu 0.0%   memory 11M   disk 121K
-      paired  matched by working directory, not reported
     provider  opencode-free
       tokens  in 24,608  out 242  reasoning 190
        calls  2 api, 6 messages, 0 tool calls
         cost  $0.0000 estimated
-     command  /usr/bin/python3 /Users/rg/.hermes/hermes-agent/hermes
 ```
 
-The `paired` line appears only when the pairing was inferred. The provider,
-tokens, calls and cost lines appear only for agents that record them, and are
-simply absent for the rest.
+A `paired` line appears when the session was matched to the process by working
+directory rather than reported, so you know before pressing `k` that the pairing
+is a guess.
 
 Enter on an ended session reopens it in a new terminal tab instead. Copilot
 chats live in the editor, so they have no reopen command and say so.
@@ -277,7 +321,7 @@ itself can answer. Nothing is invented to fill the gap.
 ## How it works
 
 The parts that are not obvious have their own page:
-[where each agent keeps its sessions](docs/internals.md), how busy and idle are
+[where each agent keeps its sessions](https://github.com/mkhuda/agent-ps/blob/main/docs/internals.md), how busy and idle are
 decided per agent, which processes count as background helpers, how a shim is
 told apart from a real session, and what the DISK column is adding up.
 
@@ -316,12 +360,12 @@ install fetches. The build is reproducible: the same source always produces the
 same bytes, so the committed executable can be checked against the tree.
 
 ```
-3085afb9b1adaa486ab468066706bb6c5625d06afb18e46fcf97a1e4b8b02c62  agent-ps
+d5f2e2bd6d35e148e461c60c7cb7bd80fce272a15efb462a7dd513955ef5a2b6  agent-ps
 ```
 
 Adding an agent takes one class and one line in the registry. See
-[CONTRIBUTING.md](CONTRIBUTING.md).
+[CONTRIBUTING.md](https://github.com/mkhuda/agent-ps/blob/main/CONTRIBUTING.md).
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](https://github.com/mkhuda/agent-ps/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkhuda/agent-ps",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A process table for coding agent sessions. Claude Code, Codex, OpenCode, Hermes, Pi, CommandCode and Copilot in one view, with models, idle time, disk use and one key to stop them.",
   "keywords": [
     "cli",