@mkhuda/agent-ps 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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.

package/README.md

@@ -1,16 +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/)
-[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![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)
 
-![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)
+[Install](#install) | [Usage](#usage) | [Agents](#agents) |
+[Scripting](#scripting) | [How it works](https://github.com/mkhuda/agent-ps/blob/main/docs/internals.md)
+
+```
+curl -fsSL https://raw.githubusercontent.com/mkhuda/agent-ps/main/install.sh | sh
+```
+
+</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
@@ -155,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,
@@ -190,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.
@@ -309,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.
 
@@ -348,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.
 
 ```
-5045dee9f7c0a85a193886e0b5fcf37020a4c36f10537f36fa453d1020aff365  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.2.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",