@mkhuda/agent-ps 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.4.0
+
+Antigravity, and a legend that was lying about one of the colours.
+
+- Google's `agy` is the eighth agent. Each conversation is its own SQLite file,
+  but the fields worth showing sit inside protobuf blobs rather than columns, so
+  they are read out one at a time: the workspace by its length prefix, the
+  opening request from its tags, and the model from the small metadata blob
+  rather than the large one, which also holds whatever the session was reading
+  and will happily hand back another agent's name.
+- Its steps carry the same status whether a turn is running or finished, so it
+  is the one agent whose busy and idle cannot be told apart. That column stays a
+  dash rather than guessing at it.
+- The legend coloured the wrong letters. It found each agent by searching the
+  line it had just built, and `copilot` contains `pi`, so two letters in the
+  middle of one name were painted in another's colour while the real `pi` was
+  left with none. Positions are recorded while the line is composed now.
+- An eighth agent had nowhere to go: a basic terminal has seven usable colours
+  and the new one would have worn the first one's. Terminals offering 256 now
+  draw from a wider palette without disturbing the seven already learned.
+
+## 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 eleven sessions across all eight agents at once, each agent named in its own colour, with columns for model, uptime, time since the last turn, cpu, memory and disk. Three antigravity sessions, two hermes background helpers, a copilot chat with no process of its own, and a busy claude session highlighted at the top.">
+
 # 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)
+![agents](https://img.shields.io/badge/agents-8-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
@@ -111,12 +124,18 @@ legend above the keys.
 | [OpenCode](https://github.com/sst/opencode) | ![blue](https://img.shields.io/badge/-3b6fd4?style=flat-square) | SQLite | directory | yes | `opencode --session` |
 | Hermes | ![red](https://img.shields.io/badge/-c0392b?style=flat-square) | SQLite | directory | yes | `hermes --resume` |
 | GitHub Copilot | ![white](https://img.shields.io/badge/-cfd3d8?style=flat-square) | VS Code storage | no process | yes | in the editor |
+| Antigravity | ![blue](https://img.shields.io/badge/-5f87ff?style=flat-square) | SQLite per conversation | directory | no | `agy --conversation` |
 
 Only Claude Code records which process is running which session, so every other
 pairing is matched on working directory and shown as a guess. OpenCode, Hermes
 and Copilot count tokens and cost, which the detail panel shows. Agents you have
 not installed are skipped, not reported as missing.
 
+Antigravity keeps each conversation in its own database, but the fields worth
+showing are inside protobuf blobs rather than columns, so they are read out one
+at a time. Its steps carry the same status whether a turn is running or has
+finished, so it is the one agent whose busy and idle cannot be told apart.
+
 Copilot is the exception to everything. It runs inside the VS Code extension
 host, so it has no process of its own: no PID, no uptime, no CPU or memory, and
 nothing to stop. What it does have is the credits each turn spent, which the free
@@ -155,7 +174,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 all eight agents, each in its own colour, the sort order spelled out 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 +209,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 +327,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 +366,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
+1a44868de812f5d0d2ac012ec97d610a34bca21884f718c7a8dffae80fb05ee6  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.4.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",