@mkhuda/agent-ps 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.6.0
+
+Reclaiming what ended sessions leave behind.
+
+- `agent-ps prune` removes the parts of an ended session that are not the
+  conversation: subagent transcripts, file history, task records, shell
+  snapshots, request dumps. On the machine it was written on that is 96M across
+  43 sessions, against 33M for deleting every session older than a month,
+  because the sessions holding the space are recent rather than old.
+- It reports by default and removes only with `--apply`. Transcripts are never
+  removed, a session with a running process is never touched whatever its age,
+  and agents that keep sessions in a database are left alone entirely.
+- `p` in the table does the same for the selected row, after a confirmation
+  naming what goes. On a running session it refuses and says why.
+- The detail panel marks which parts of a session can be pruned, and the line
+  above the keys reports the total when there is one.
+- One confirmation path now serves every destructive key, rather than each
+  growing its own.
+- Release pages take their title and notes from the changelog instead of the
+  commit list.
+
+## 0.5.0
+
+The token counts four agents were already writing.
+
+- Token counts for Claude Code, Codex, Pi and CommandCode, which all record
+  what a turn spent and were simply never read. Seven of the eight agents now
+  report what a session cost.
+- The counts are summed over a whole log, which is the one thing here that
+  reads a file end to end, so it happens only for the session whose detail
+  panel is open. Logs are append only, so a session that grew costs the bytes
+  it just wrote rather than all of it again.
+- `agent-ps list` now says when `ps` or `lsof` failed even where the table came
+  back with rows, rather than only when it came back empty.
+- The tests run in CI, across every supported interpreter.
+
 ## 0.4.0
 
 Antigravity, and a legend that was lying about one of the colours.

package/README.md

@@ -28,7 +28,7 @@ curl -fsSL https://raw.githubusercontent.com/mkhuda/agent-ps/main/install.sh | s
 `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
 idle for three days, or which rows are background daemons that outlived the
-terminal that started them. It also misses the other six agents entirely.
+terminal that started them. It also misses the other seven agents entirely.
 
 agent-ps lists every session with its agent, model, working directory, uptime,
 idle time and disk footprint, then stops one process tree, every background
@@ -68,8 +68,7 @@ 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`.
+Either way the command it gives you is `agent-ps`.
 
 ### Just the file
 
@@ -98,7 +97,7 @@ looking at.
 
 ### What it needs, and how to remove it
 
-Python 3.8 or later and nothing from PyPI. Tested on 3.8, 3.9, 3.10 and 3.14.
+Python 3.8 or later and nothing from PyPI. Tested on 3.8, 3.9, 3.12 and 3.13.
 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.
@@ -115,31 +114,23 @@ agent-ps only ever reads the agents' own files.
 Each agent keeps its own colour in the table, and the same colours label the
 legend above the keys.
 
-| Agent | | Sessions in | Paired by | Tokens | Reopened with |
-|---|---|---|---|---|---|
-| [Claude Code](https://claude.com/claude-code) | ![yellow](https://img.shields.io/badge/-d4a72c?style=flat-square) | JSONL | the agent itself | no | `claude --resume` |
-| [Pi](https://pi.dev) | ![cyan](https://img.shields.io/badge/-00a3a3?style=flat-square) | JSONL | directory | no | `pi --session` |
-| CommandCode | ![magenta](https://img.shields.io/badge/-b83fb8?style=flat-square) | JSONL | directory | no | `cmd --resume` |
-| [Codex CLI](https://github.com/openai/codex) | ![green](https://img.shields.io/badge/-3f9e3f?style=flat-square) | JSONL | directory | no | `codex resume` |
-| [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
-tier meters and nothing else surfaces. A chat counts as open while its workspace
+| Agent | | Sessions in | Paired by | Reopened with |
+|---|---|---|---|---|
+| [Claude Code](https://claude.com/claude-code) | ![yellow](https://img.shields.io/badge/-d4a72c?style=flat-square) | JSONL | the agent itself | `claude --resume` |
+| [Pi](https://pi.dev) | ![cyan](https://img.shields.io/badge/-00a3a3?style=flat-square) | JSONL | directory | `pi --session` |
+| CommandCode | ![magenta](https://img.shields.io/badge/-b83fb8?style=flat-square) | JSONL | directory | `cmd --resume` |
+| [Codex CLI](https://github.com/openai/codex) | ![green](https://img.shields.io/badge/-3f9e3f?style=flat-square) | JSONL | directory | `codex resume` |
+| [OpenCode](https://github.com/sst/opencode) | ![blue](https://img.shields.io/badge/-3b6fd4?style=flat-square) | SQLite | directory | `opencode --session` |
+| Hermes | ![red](https://img.shields.io/badge/-c0392b?style=flat-square) | SQLite | directory | `hermes --resume` |
+| GitHub Copilot | ![white](https://img.shields.io/badge/-cfd3d8?style=flat-square) | VS Code storage | no process | in the editor |
+| Antigravity | ![blue](https://img.shields.io/badge/-5f87ff?style=flat-square) | SQLite per conversation | directory | `agy --conversation` |
+
+Only Claude Code records which process is running which session. Every other
+pairing is matched on working directory and shown as a guess. Tokens and cost
+appear in the detail panel.
+
+Copilot is the exception: it runs inside the VS Code extension host, so it has no
+process of its own and nothing to stop. A chat counts as open while its workspace
 is open in the editor.
 
 ## Usage
@@ -163,6 +154,7 @@ something.
 | `S` | reverse the direction |
 | `k` | stop the selected process and its children, after confirming |
 | `b` | stop every background helper, after confirming |
+| `p` | remove what the selected ended session left behind, after confirming |
 | `y`, `n` | answer a confirmation |
 | `e` | show or hide ended sessions |
 | `/` | filter by session, title, agent, model, directory, or PID |
@@ -176,9 +168,8 @@ screen in its own colour and, on the right, what the table is sorted by:
 
 ![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,
-and it is where a note appears for a few seconds after you act on something.
+That middle line is the key to the colours, names the sort order in words, and
+is where a note appears for a few seconds after you act on something.
 
 Backspacing a filter down to nothing leaves filter mode, so the key bar comes
 back without reaching for escape.
@@ -209,20 +200,17 @@ ended sessions, then `s` until DISK is marked.
 
 ### The detail panel
 
-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.
+Enter on a live session opens everything known about it, in four groups: what
+the session is, what it is doing to the machine, what it has cost, and the
+command line.
 
 <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.
+The disk total is broken down by what is holding it, since transcript and file
+history call for different answers.
 
-Where the agent counts tokens, they are here too. Hermes and OpenCode report
-cost, Copilot reports the credits a turn spent:
+Tokens and cost are here too, and Copilot reports the credits a turn spent:
 
 ```
     provider  opencode-free
@@ -236,14 +224,13 @@ 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.
+chats reopen in the editor.
 
 ### The advisory line
 
 A line above the keys points out whatever is worth a look: background helpers
 left running, sessions untouched for a day, or ended sessions you could resume.
-It names the key that acts on it, and only ever shows one thing, since a wall of
-warnings teaches people to ignore the line.
+It names the key that acts on it, and shows one thing at a time.
 
 ## Scripting
 
@@ -253,6 +240,9 @@ agent-ps list --all               # include ended sessions
 agent-ps list --json              # machine readable, with idle seconds
 agent-ps list --limit 100         # how many ended sessions (default 40)
 agent-ps list --filter benchmark  # same match as the / key
+agent-ps prune                    # what ended sessions left, minus the conversation
+agent-ps prune --older-than 30d   # only sessions idle that long (default 7d)
+agent-ps prune --apply            # actually remove it
 agent-ps agents                   # which agents were found, and where
 agent-ps --agent codex list       # one agent, or a comma separated list
 agent-ps stop 32244               # stop one process tree
@@ -267,6 +257,30 @@ agent-ps --version
 Piping works without a subcommand: with stdout not a terminal, agent-ps prints
 the table and exits.
 
+## Reclaiming space
+
+A session writes more than its conversation. Claude Code alone keeps subagent
+transcripts, file history for `/rewind`, task records and a session
+environment, and on this machine those came to a fifth of everything on disk.
+
+```bash
+agent-ps prune
+```
+
+Reports and removes nothing. It lists what ended sessions left behind, grouped
+by what it is and which sessions hold the most, and `--apply` removes it.
+
+In the table, `p` does the same for the row you are on, and the detail panel
+marks which parts of a session those are. On a session that is still running it
+refuses and says why rather than going quiet.
+
+Three things it will not do. It never touches a transcript, so every session
+stays resumable. It never touches a session with a running process, whatever
+its age, because file history is what `/rewind` reaches for. And it never
+touches OpenCode, Copilot or Antigravity, whose sessions are rows in a database
+the agent may have open: agent-ps reads, and does not write, the stores it
+did not create.
+
 ## What each column means
 
 | Column | Meaning |
@@ -281,18 +295,14 @@ the table and exits.
 | CPU, MEM | the same `ps` call |
 | DISK | everything that session left on disk |
 | DIR | the working directory |
-| TITLE | the session title, or its opening prompt where the agent keeps none |
+| TITLE | the session title, or its opening prompt |
 
-UPTIME and ACTIVE often disagree, and that is the point. A process can be five
-days old and have answered a minute ago. UPTIME comes from the process table,
-ACTIVE from the modification time of the log, which is appended on every turn,
-so an ended session shows a dash under UPTIME and only ACTIVE says how stale it
-is.
+UPTIME and ACTIVE often disagree: a process can be five days old and have
+answered a minute ago. UPTIME comes from the process table, ACTIVE from the log,
+which is appended on every turn.
 
-Each agent gets its own colour in the AGENT column, assigned in registry order,
-and the same colours appear in the legend, which makes that line the key to the
-palette. A selected row keeps its own highlight rather than being broken up, so
-the cursor stays unmistakable. Terminals without colour fall back to plain text.
+Each agent has its own colour, and the legend above the keys is the key to it.
+Terminals without colour fall back to plain text.
 
 ## A PID marked with a question mark
 
@@ -366,7 +376,7 @@ install fetches. The build is reproducible: the same source always produces the
 same bytes, so the committed executable can be checked against the tree.
 
 ```
-1a44868de812f5d0d2ac012ec97d610a34bca21884f718c7a8dffae80fb05ee6  agent-ps
+b57e60c153471ce8a5630d72a2688633b7d6ff9c5359b372e12fc03d0d9379d9  agent-ps
 ```
 
 Adding an agent takes one class and one line in the registry. See

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkhuda/agent-ps",
-  "version": "0.4.0",
+  "version": "0.6.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",