agentop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tamas Kalman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# agentop
+
+[![npm version](https://img.shields.io/npm/v/agentop.svg)](https://www.npmjs.com/package/agentop)
+[![CI](https://github.com/ktamas77/agentop/actions/workflows/ci.yml/badge.svg)](https://github.com/ktamas77/agentop/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> `top`, but for your running **Claude Code agents**.
+
+A zero-dependency terminal dashboard that shows every `claude` CLI session
+running on your machine — live, refreshing like `top`/`htop`. See at a glance
+which projects have agents working, what model they're on, which git branch
+they're on, and what each one is doing *right now* (running a tool, thinking,
+or waiting for you).
+
+![agentop in action](docs/screenshot.png)
+
+## Usage
+
+No install needed — run it with `npx`:
+
+```sh
+npx agentop
+```
+
+Or install globally:
+
+```sh
+npm install -g agentop
+agentop
+```
+
+### Live keys
+
+| Key | Action |
+|-----|--------|
+| `q` / `Esc` / `Ctrl-C` | Quit |
+| `s` | Cycle the sort column |
+| `r` | Reverse the sort order |
+| `+` / `-` | Increase / decrease the refresh interval |
+
+### Options
+
+```
+-d, --interval <sec>   Refresh interval in seconds (default: 2)
+-s, --sort <key>       Sort by: cpu, mem, up, idle, project, pid (default: cpu)
+-r, --reverse          Reverse sort order
+-n, --once             Print a single snapshot and exit (no live UI)
+    --json             Print agents as JSON and exit
+    --no-color         Disable ANSI colors
+-h, --help             Show help
+-v, --version          Show version
+```
+
+`--once` and `--json` make `agentop` scriptable:
+
+```sh
+agentop --json | jq '.[] | select(.state == "working") | .project'
+watch -n5 'agentop --once'
+```
+
+## Columns
+
+| Column | Meaning |
+|--------|---------|
+| **PID** | OS process id of the `claude` CLI session |
+| **MODEL** | Model the session is using (e.g. `opus-4-8`) |
+| **PROJECT** | Working directory basename of the agent |
+| **BRANCH** | Git branch the session is on |
+| **STATE** | `working` (running a tool) · `thinking` · `replied` · `waiting` · `idle` · `stalled` |
+| **%CPU** | Process CPU usage |
+| **MEM** | Resident memory |
+| **UP** | How long the process has been running |
+| **IDLE** | Time since the last transcript activity |
+| **ACTIVITY** | What the agent is doing right now (current tool, prompt, …) |
+
+## How it works
+
+`agentop` reads only local state — nothing is sent anywhere:
+
+1. It lists running **`claude` CLI processes** with `ps` (the desktop app and
+   its helpers are filtered out), and resolves each one's working directory
+   via `/proc` on Linux or `lsof` on macOS.
+2. It joins each process to its **session transcript** under
+   `~/.claude/projects/<encoded-cwd>/<session>.jsonl`, matching on the working
+   directory.
+3. It reads just the **tail** of each matching transcript to extract the model,
+   git branch, version, last-activity time, and current tool call — then renders
+   it all as a `top`-style table.
+
+## Requirements
+
+- Node.js ≥ 16 to run (the dev test suite uses Node's built-in runner, which needs ≥ 18)
+- macOS or Linux (`ps`, plus `lsof` on macOS)
+
+## Development
+
+```sh
+npm install        # also installs the Husky pre-commit hook
+npm test           # unit + CLI tests (node --test, run in parallel)
+npm run lint       # eslint
+npm run typecheck  # tsc --noEmit (type-checks the JS via JSDoc/inference)
+npm run format     # prettier --write
+npm run check      # format:check + lint + typecheck + test (what CI runs)
+```
+
+A Husky **pre-commit** hook runs `lint-staged` (Prettier + ESLint on staged
+files), then the type-check and the full test suite. CI runs the same checks as
+independent parallel jobs (`format`, `lint`, `typecheck`, and a `test` matrix
+across macOS/Linux × Node 18/20/22).
+
+## License
+
+MIT © Tamas Kalman

package/bin/agentop.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+'use strict';
+
+const { collectAgents } = require('../lib/collect');
+const { buildFrame, sortAgents, SORTS } = require('../lib/render');
+const { runLive } = require('../lib/ui');
+const c = require('../lib/colors');
+const pkg = require('../package.json');
+
+function parseArgs(argv) {
+  const opts = {
+    interval: 2,
+    sort: 'cpu',
+    reverse: false,
+    once: false,
+    json: false,
+    color: undefined,
+  };
+  const args = argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '-h':
+      case '--help':
+        printHelp();
+        process.exit(0);
+        break;
+      case '-v':
+      case '--version':
+        process.stdout.write(`agentop ${pkg.version}\n`);
+        process.exit(0);
+        break;
+      case '-n':
+      case '--once':
+        opts.once = true;
+        break;
+      case '--json':
+        opts.json = true;
+        opts.once = true;
+        break;
+      case '--no-color':
+        opts.color = false;
+        break;
+      case '-d':
+      case '--interval': {
+        const val = parseFloat(args[++i]);
+        if (!isFinite(val) || val <= 0) fail(`invalid interval: ${args[i]}`);
+        opts.interval = Math.max(1, Math.round(val));
+        break;
+      }
+      case '-s':
+      case '--sort': {
+        const val = args[++i];
+        if (!SORTS.includes(val)) fail(`invalid sort key: ${val} (choose: ${SORTS.join(', ')})`);
+        opts.sort = val;
+        break;
+      }
+      case '-r':
+      case '--reverse':
+        opts.reverse = true;
+        break;
+      default:
+        fail(`unknown option: ${a}`);
+    }
+  }
+  return opts;
+}
+
+function fail(msg) {
+  process.stderr.write(`agentop: ${msg}\n`);
+  process.stderr.write(`Try 'agentop --help'.\n`);
+  process.exit(2);
+}
+
+function printHelp() {
+  process.stdout.write(`agentop — top, but for your running Claude Code agents
+
+USAGE
+  agentop [options]
+
+OPTIONS
+  -d, --interval <sec>   Refresh interval in seconds (default: 2)
+  -s, --sort <key>       Sort by: ${SORTS.join(', ')} (default: cpu)
+  -r, --reverse          Reverse sort order
+  -n, --once             Print a single snapshot and exit (no live UI)
+      --json             Print agents as JSON and exit
+      --no-color         Disable ANSI colors
+  -h, --help             Show this help
+  -v, --version          Show version
+
+LIVE KEYS
+  q / Esc / Ctrl-C       Quit
+  s                      Cycle sort column
+  r                      Reverse sort order
+  +/-                    Increase / decrease refresh interval
+
+WHAT IT SHOWS
+  Every running 'claude' CLI session on this machine, joined to its
+  project, git branch, model, and current activity (read live from the
+  session transcripts under ~/.claude/projects).
+`);
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  if (opts.color === false) c.setEnabled(false);
+
+  if (opts.json) {
+    const agents = sortAgents(collectAgents(), opts.sort, opts.reverse);
+    process.stdout.write(JSON.stringify(agents, null, 2) + '\n');
+    return;
+  }
+
+  if (opts.once || !process.stdout.isTTY) {
+    const agents = sortAgents(collectAgents(), opts.sort, opts.reverse);
+    const frame = buildFrame(agents, {
+      width: process.stdout.columns || 100,
+      height: Math.max(agents.length + 6, 10),
+      interval: opts.interval,
+      sort: opts.sort,
+      reverse: opts.reverse,
+      once: true,
+    });
+    process.stdout.write(frame + '\n');
+    return;
+  }
+
+  runLive(opts);
+}
+
+main();

package/lib/collect.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const path = require('path');
+const { listClaudeProcesses, resolveCwds } = require('./processes');
+const { listSessionFiles, readTailObjects, summarizeSession } = require('./sessions');
+
+const MAX_SESSION_SCAN = 120; // cap transcript reads per refresh
+
+// Build the list of running-agent records by joining live processes to their
+// most recent matching session transcript (matched on working directory).
+function collectAgents() {
+  const procs = listClaudeProcesses();
+  resolveCwds(procs);
+
+  // How many running processes live in each cwd (handles >1 agent per dir).
+  const needByCwd = new Map();
+  for (const p of procs) {
+    if (!p.cwd) continue;
+    needByCwd.set(p.cwd, (needByCwd.get(p.cwd) || 0) + 1);
+  }
+
+  // Walk sessions newest-first; collect candidate session summaries per cwd,
+  // up to the number of processes that actually live there.
+  const sessionsByCwd = new Map(); // cwd -> [summary, ...] newest first
+  const files = listSessionFiles();
+  let scanned = 0;
+  for (const f of files) {
+    if (needByCwd.size === 0) break;
+    if (scanned >= MAX_SESSION_SCAN) break;
+    scanned++;
+    const objs = readTailObjects(f.file);
+    if (!objs.length) continue;
+    const sum = summarizeSession(objs);
+    if (!sum.cwd || !needByCwd.has(sum.cwd)) continue;
+    const arr = sessionsByCwd.get(sum.cwd) || [];
+    if (arr.length >= needByCwd.get(sum.cwd)) continue;
+    sum.sessionId = f.sessionId;
+    sum.mtimeMs = f.mtimeMs;
+    arr.push(sum);
+    sessionsByCwd.set(sum.cwd, arr);
+  }
+
+  const now = Date.now();
+  const agents = procs.map((p) => {
+    const pool = sessionsByCwd.get(p.cwd);
+    const session = pool && pool.length ? pool.shift() : null;
+    const lastTs = session && session.lastTs ? session.lastTs : null;
+    const idleSec = lastTs ? Math.max(0, (now - lastTs) / 1000) : null;
+    return {
+      pid: p.pid,
+      cpu: p.cpu,
+      rssKb: p.rssKb,
+      uptimeSec: p.uptimeSec,
+      cwd: p.cwd,
+      project: p.cwd ? path.basename(p.cwd) : '(unknown)',
+      args: p.args,
+      model: session ? session.model : null,
+      version: session ? session.version : null,
+      gitBranch: session ? session.gitBranch : null,
+      sessionId: session ? session.sessionId : null,
+      lastPrompt: session ? session.lastPrompt : null,
+      rawState: session ? session.state : 'no-session',
+      detail: session ? session.detail : '',
+      idleSec,
+      state: classifyState(session ? session.state : 'no-session', idleSec),
+    };
+  });
+
+  return agents;
+}
+
+// Combine transcript activity with how long ago it happened into a display state.
+function classifyState(rawState, idleSec) {
+  if (rawState === 'no-session') return 'live';
+  if (idleSec == null) return 'idle';
+  if (rawState === 'tool') return idleSec < 120 ? 'working' : 'stalled';
+  if (rawState === 'thinking') return idleSec < 120 ? 'thinking' : 'stalled';
+  if (rawState === 'replied') return idleSec < 30 ? 'replied' : 'waiting';
+  return idleSec < 30 ? 'active' : 'idle';
+}
+
+module.exports = { collectAgents, classifyState };

package/lib/colors.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// Minimal, dependency-free ANSI styling. Honors NO_COLOR and non-TTY output.
+let enabled = process.stdout.isTTY && !process.env.NO_COLOR;
+
+function setEnabled(value) {
+  enabled = Boolean(value);
+}
+
+const CODES = {
+  reset: 0,
+  bold: 1,
+  dim: 2,
+  italic: 3,
+  underline: 4,
+  inverse: 7,
+  black: 30,
+  red: 31,
+  green: 32,
+  yellow: 33,
+  blue: 34,
+  magenta: 35,
+  cyan: 36,
+  white: 37,
+  gray: 90,
+  brightRed: 91,
+  brightGreen: 92,
+  brightYellow: 93,
+  brightBlue: 94,
+  brightMagenta: 95,
+  brightCyan: 96,
+};
+
+function wrap(name) {
+  return (str) => (enabled ? `\x1b[${CODES[name]}m${str}\x1b[0m` : String(str));
+}
+
+const colors = {
+  setEnabled,
+  get enabled() {
+    return enabled;
+  },
+};
+for (const name of Object.keys(CODES)) {
+  if (name === 'reset') continue;
+  colors[name] = wrap(name);
+}
+
+// Strip ANSI for width calculations.
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+colors.strip = (str) => String(str).replace(ANSI_RE, '');
+colors.width = (str) => colors.strip(str).length;
+
+module.exports = colors;

package/lib/format.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const c = require('./colors');
+
+// claude-opus-4-8 -> opus-4-8 ; claude-haiku-4-5-20251001 -> haiku-4-5
+function shortModel(model) {
+  if (!model) return '?';
+  return String(model)
+    .replace(/^claude-/, '')
+    .replace(/-\d{8}$/, '') // drop trailing date stamp
+    .replace(/\[1m\]$/, ''); // drop context-window suffix
+}
+
+// Parse ps ELAPSED format ([[DD-]HH:]MM:SS) into seconds.
+function parseEtime(etime) {
+  if (!etime) return 0;
+  let days = 0;
+  let rest = etime;
+  if (rest.includes('-')) {
+    const [d, r] = rest.split('-');
+    days = parseInt(d, 10) || 0;
+    rest = r;
+  }
+  const parts = rest.split(':').map((n) => parseInt(n, 10) || 0);
+  let h = 0;
+  let m = 0;
+  let s = 0;
+  if (parts.length === 3) [h, m, s] = parts;
+  else if (parts.length === 2) [m, s] = parts;
+  else [s] = parts;
+  return days * 86400 + h * 3600 + m * 60 + s;
+}
+
+// Compact duration: 9s, 3m, 1h12, 2d3h
+function dur(seconds) {
+  if (seconds == null || !isFinite(seconds)) return '-';
+  seconds = Math.max(0, Math.floor(seconds));
+  if (seconds < 60) return `${seconds}s`;
+  const m = Math.floor(seconds / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const remM = m % 60;
+  if (h < 24) return remM ? `${h}h${String(remM).padStart(2, '0')}` : `${h}h`;
+  const d = Math.floor(h / 24);
+  const remH = h % 24;
+  return remH ? `${d}d${remH}h` : `${d}d`;
+}
+
+// KB (as reported by ps rss) -> human readable.
+function memFromKb(kb) {
+  if (kb == null) return '-';
+  const bytes = kb * 1024;
+  return bytes2human(bytes);
+}
+
+function bytes2human(bytes) {
+  const units = ['B', 'K', 'M', 'G', 'T'];
+  let n = bytes;
+  let i = 0;
+  while (n >= 1024 && i < units.length - 1) {
+    n /= 1024;
+    i++;
+  }
+  const val = n >= 100 || i === 0 ? Math.round(n) : n.toFixed(1);
+  return `${val}${units[i]}`;
+}
+
+// Pad/truncate a string to an exact visible width (ANSI-aware).
+function fit(str, width, align = 'left') {
+  str = str == null ? '' : String(str);
+  const w = c.width(str);
+  if (w === width) return str;
+  if (w > width) {
+    // Truncate raw text (assumes no color in truncated cells; we color after fit).
+    const plain = c.strip(str);
+    if (width <= 1) return plain.slice(0, width);
+    return plain.slice(0, width - 1) + '…';
+  }
+  const pad = ' '.repeat(width - w);
+  return align === 'right' ? pad + str : str + pad;
+}
+
+module.exports = { shortModel, parseEtime, dur, memFromKb, bytes2human, fit };

package/lib/processes.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const { parseEtime } = require('./format');
+
+// Is this command line a Claude Code CLI session (not the desktop app / helpers)?
+function isClaudeCli(args) {
+  if (!args) return false;
+  // The Electron desktop app and its helpers all live under Claude.app.
+  if (args.includes('Claude.app')) return false;
+  if (/Claude Helper|chrome-native-host|crashpad/.test(args)) return false;
+  // The first token is the executable; accept it if its basename is exactly "claude",
+  // or it's `node …/claude[.js]` (global npm install / local dev).
+  const tokens = args.trim().split(/\s+/);
+  const exe = tokens[0] || '';
+  const base = exe.split('/').pop();
+  if (base === 'claude') return true;
+  if (/^node$/.test(base) || /\/node$/.test(exe)) {
+    return tokens.slice(1).some((t) => {
+      const b = t.split('/').pop();
+      return b === 'claude' || (b === 'cli.js' && /claude/.test(t));
+    });
+  }
+  return false;
+}
+
+// List running Claude CLI processes with pid, cpu, rss(KB), elapsed seconds, args.
+function listClaudeProcesses() {
+  let out;
+  try {
+    out = execFileSync('ps', ['-axww', '-o', 'pid=,pcpu=,rss=,etime=,args='], {
+      encoding: 'utf8',
+      maxBuffer: 32 * 1024 * 1024,
+    });
+  } catch (e) {
+    return [];
+  }
+  const procs = [];
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue;
+    const m = line.match(/^\s*(\d+)\s+([\d.]+)\s+(\d+)\s+(\S+)\s+(.*)$/);
+    if (!m) continue;
+    const [, pid, pcpu, rss, etime, args] = m;
+    if (!isClaudeCli(args)) continue;
+    procs.push({
+      pid: parseInt(pid, 10),
+      cpu: parseFloat(pcpu),
+      rssKb: parseInt(rss, 10),
+      uptimeSec: parseEtime(etime),
+      args: args.trim(),
+      cwd: null,
+    });
+  }
+  return procs;
+}
+
+// Resolve current working directory for each pid. Uses /proc on Linux, lsof on macOS.
+function resolveCwds(procs) {
+  if (procs.length === 0) return;
+  if (process.platform === 'linux') {
+    for (const p of procs) {
+      try {
+        p.cwd = fs.readlinkSync(`/proc/${p.pid}/cwd`);
+      } catch (e) {
+        /* process may have exited or be inaccessible */
+      }
+    }
+    return;
+  }
+  // macOS / BSD: one batched lsof call for all pids.
+  try {
+    const pids = procs.map((p) => p.pid).join(',');
+    const out = execFileSync('lsof', ['-a', '-p', pids, '-d', 'cwd', '-Fpn'], {
+      encoding: 'utf8',
+      maxBuffer: 8 * 1024 * 1024,
+    });
+    const byPid = new Map(procs.map((p) => [p.pid, p]));
+    let cur = null;
+    for (const line of out.split('\n')) {
+      if (line[0] === 'p') cur = byPid.get(parseInt(line.slice(1), 10)) || null;
+      else if (line[0] === 'n' && cur) cur.cwd = line.slice(1);
+    }
+  } catch (e) {
+    /* lsof unavailable; cwd stays null and agents still show as "(unknown dir)" */
+  }
+}
+
+module.exports = { listClaudeProcesses, resolveCwds, isClaudeCli };

package/lib/render.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const os = require('os');
+const c = require('./colors');
+const { shortModel, dur, memFromKb, fit } = require('./format');
+
+// State -> { dot, color } for the STATE column.
+const STATE_STYLE = {
+  working: { dot: '●', color: 'brightGreen', label: 'working' },
+  thinking: { dot: '●', color: 'brightCyan', label: 'thinking' },
+  replied: { dot: '○', color: 'green', label: 'replied' },
+  active: { dot: '●', color: 'green', label: 'active' },
+  waiting: { dot: '○', color: 'yellow', label: 'waiting' },
+  idle: { dot: '○', color: 'gray', label: 'idle' },
+  stalled: { dot: '◐', color: 'brightYellow', label: 'stalled' },
+  live: { dot: '●', color: 'blue', label: 'live' },
+};
+
+const SORTS = ['cpu', 'mem', 'up', 'idle', 'project', 'pid'];
+
+function sortAgents(agents, sortKey, reverse) {
+  const cmp =
+    {
+      cpu: (a, b) => b.cpu - a.cpu,
+      mem: (a, b) => b.rssKb - a.rssKb,
+      up: (a, b) => b.uptimeSec - a.uptimeSec,
+      idle: (a, b) => (a.idleSec ?? Infinity) - (b.idleSec ?? Infinity),
+      project: (a, b) => a.project.localeCompare(b.project),
+      pid: (a, b) => a.pid - b.pid,
+    }[sortKey] || (() => 0);
+  const sorted = agents.slice().sort(cmp);
+  if (reverse) sorted.reverse();
+  return sorted;
+}
+
+// Column layout. width 0 == flex (takes the remaining terminal width).
+const COLUMNS = [
+  { key: 'pid', header: 'PID', width: 7, align: 'right' },
+  { key: 'model', header: 'MODEL', width: 12, align: 'left' },
+  { key: 'project', header: 'PROJECT', width: 20, align: 'left' },
+  { key: 'branch', header: 'BRANCH', width: 12, align: 'left' },
+  { key: 'state', header: 'STATE', width: 10, align: 'left' },
+  { key: 'cpu', header: '%CPU', width: 5, align: 'right' },
+  { key: 'mem', header: 'MEM', width: 6, align: 'right' },
+  { key: 'up', header: 'UP', width: 6, align: 'right' },
+  { key: 'idle', header: 'IDLE', width: 6, align: 'right' },
+  { key: 'activity', header: 'ACTIVITY', width: 0, align: 'left' },
+];
+
+function buildFrame(agents, opts) {
+  const width = opts.width || process.stdout.columns || 100;
+  const height = opts.height || process.stdout.rows || 30;
+  const lines = [];
+
+  // ---- Header ----
+  const totalCpu = agents.reduce((s, a) => s + (a.cpu || 0), 0);
+  const totalMem = agents.reduce((s, a) => s + (a.rssKb || 0), 0);
+  const clock = new Date().toLocaleTimeString();
+  const title = c.bold(c.brightCyan('agentop')) + c.dim(' — Claude agents');
+  const count = agents.length === 1 ? '1 agent' : `${agents.length} agents`;
+  const right = c.dim(`${clock}  ↻${opts.interval}s`);
+  lines.push(fit(padBetween(`${title}  ${c.bold(String(count))} running`, right, width), width));
+  lines.push(
+    fit(
+      padBetween(
+        c.dim(
+          `CPU ${totalCpu.toFixed(1)}%   MEM ${memFromKb(totalMem)}   sort:${opts.sort}${opts.reverse ? '↑' : '↓'}`,
+        ),
+        c.dim(`host ${os.hostname().split('.')[0]}`),
+        width,
+      ),
+      width,
+    ),
+  );
+  lines.push('');
+
+  // ---- Resolve flex width for ACTIVITY ----
+  const fixed = COLUMNS.filter((col) => col.width > 0).reduce((s, col) => s + col.width, 0);
+  const gaps = COLUMNS.length - 1; // single space between columns
+  const flex = Math.max(10, width - fixed - gaps);
+
+  // ---- Header row ----
+  const headerCells = COLUMNS.map((col) => {
+    const w = col.width === 0 ? flex : col.width;
+    return fit(col.header, w, col.align);
+  });
+  lines.push(c.bold(c.inverse(fit(headerCells.join(' '), width))));
+
+  // ---- Rows ----
+  const bodyRows = Math.max(0, height - lines.length - 1); // leave 1 line for footer
+  const shown = agents.slice(0, bodyRows);
+  for (const a of shown) {
+    lines.push(fit(renderRow(a, flex), width));
+  }
+
+  if (agents.length === 0) {
+    lines.push('');
+    lines.push(fit(c.dim('  No running Claude agents found.'), width));
+    lines.push(fit(c.dim('  Start one with `claude` in any project, then come back.'), width));
+  }
+
+  // ---- Footer ----
+  while (lines.length < height - 1) lines.push('');
+  const footer = opts.once
+    ? ''
+    : c.inverse(
+        fit(
+          ' q quit   s sort   r reverse   +/- interval' +
+            (agents.length > bodyRows ? `   (+${agents.length - bodyRows} more)` : ''),
+          width,
+        ),
+      );
+  if (footer) lines.push(footer);
+
+  return lines.join('\n');
+}
+
+function renderRow(a, flex) {
+  const st = STATE_STYLE[a.state] || STATE_STYLE.idle;
+  const cells = {
+    pid: String(a.pid),
+    model: shortModel(a.model),
+    project: a.project,
+    branch: a.gitBranch && a.gitBranch !== 'HEAD' ? a.gitBranch : a.gitBranch || '-',
+    state: `${st.dot} ${st.label}`,
+    cpu: (a.cpu || 0).toFixed(1),
+    mem: memFromKb(a.rssKb),
+    up: dur(a.uptimeSec),
+    idle: a.idleSec == null ? '-' : dur(a.idleSec),
+    activity: activityText(a),
+  };
+
+  const out = COLUMNS.map((col) => {
+    const width = col.width === 0 ? flex : col.width;
+    const text = fit(cells[col.key], width, col.align);
+    return colorCell(col.key, text, a, st);
+  });
+  return out.join(' ');
+}
+
+function colorCell(key, text, a, st) {
+  switch (key) {
+    case 'pid':
+      return c.dim(text);
+    case 'model':
+      return c.brightMagenta(text);
+    case 'project':
+      return c.bold(text);
+    case 'branch':
+      return c.cyan(text);
+    case 'state':
+      return c[st.color] ? c[st.color](text) : text;
+    case 'cpu':
+      return (a.cpu || 0) > 20 ? c.brightYellow(text) : text;
+    case 'activity':
+      return c.dim(text);
+    default:
+      return text;
+  }
+}
+
+function activityText(a) {
+  if (a.rawState === 'no-session') return a.args || '(no transcript)';
+  if (a.rawState === 'tool') return `⚙ ${a.detail}`;
+  if (a.rawState === 'thinking') return a.detail ? `▸ ${a.detail}` : '▸ thinking…';
+  if (a.rawState === 'replied') return a.detail || 'awaiting input';
+  return a.detail || '';
+}
+
+// Left + right text on one line, padded to width (ANSI-aware).
+function padBetween(left, right, width) {
+  const lw = c.width(left);
+  const rw = c.width(right);
+  const space = Math.max(1, width - lw - rw);
+  return left + ' '.repeat(space) + right;
+}
+
+module.exports = { buildFrame, sortAgents, SORTS };

package/lib/sessions.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function projectsRoot() {
+  return path.join(os.homedir(), '.claude', 'projects');
+}
+
+// List every session transcript across all projects, newest first.
+function listSessionFiles() {
+  const root = projectsRoot();
+  let dirs;
+  try {
+    dirs = fs.readdirSync(root, { withFileTypes: true });
+  } catch (e) {
+    return [];
+  }
+  const files = [];
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue;
+    const dir = path.join(root, d.name);
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch (e) {
+      continue;
+    }
+    for (const name of entries) {
+      if (!name.endsWith('.jsonl')) continue;
+      const file = path.join(dir, name);
+      try {
+        const st = fs.statSync(file);
+        files.push({ file, dir, mtimeMs: st.mtimeMs, sessionId: name.replace(/\.jsonl$/, '') });
+      } catch (e) {
+        /* skip */
+      }
+    }
+  }
+  files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return files;
+}
+
+// Read the last `bytes` of a file and return parsed JSONL objects (dropping a
+// partial first line). Cheap way to inspect a long transcript's recent activity.
+function readTailObjects(file, bytes = 24 * 1024) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+    const { size } = fs.fstatSync(fd);
+    const start = Math.max(0, size - bytes);
+    const len = size - start;
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, start);
+    let text = buf.toString('utf8');
+    if (start > 0) {
+      const nl = text.indexOf('\n');
+      if (nl !== -1) text = text.slice(nl + 1); // drop partial leading line
+    }
+    const objs = [];
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        objs.push(JSON.parse(line));
+      } catch (e) {
+        /* skip malformed/truncated line */
+      }
+    }
+    return objs;
+  } catch (e) {
+    return [];
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch (e) {
+        /* ignore */
+      }
+    }
+  }
+}
+
+// Derive a human summary of a session from its tail objects.
+function summarizeSession(objs) {
+  let cwd = null;
+  let model = null;
+  let version = null;
+  let gitBranch = null;
+  let lastTs = null;
+  let lastPrompt = null;
+
+  for (const o of objs) {
+    if (o.cwd) cwd = o.cwd;
+    if (o.version) version = o.version;
+    if (o.gitBranch) gitBranch = o.gitBranch;
+    if (o.timestamp) lastTs = o.timestamp;
+    if (o.type === 'assistant' && o.message && o.message.model) model = o.message.model;
+    if (o.type === 'last-prompt' && o.lastPrompt) lastPrompt = o.lastPrompt;
+  }
+
+  const last = objs.length ? objs[objs.length - 1] : null;
+  const activity = deriveActivity(objs, last);
+
+  return {
+    cwd,
+    model,
+    version,
+    gitBranch,
+    lastTs: lastTs ? Date.parse(lastTs) : null,
+    lastPrompt,
+    state: activity.state,
+    detail: activity.detail,
+  };
+}
+
+// Classify what the agent is doing from the last meaningful transcript entry.
+function deriveActivity(objs, last) {
+  if (!last) return { state: 'unknown', detail: '' };
+
+  if (last.type === 'assistant' && last.message) {
+    const content = Array.isArray(last.message.content) ? last.message.content : [];
+    const tools = content.filter((b) => b && b.type === 'tool_use').map((b) => b.name);
+    if (tools.length) {
+      return { state: 'tool', detail: tools.join(', ') };
+    }
+    const text = content.find((b) => b && b.type === 'text');
+    return { state: 'replied', detail: text ? firstLine(text.text) : '' };
+  }
+
+  if (last.type === 'user' && last.message) {
+    const content = last.message.content;
+    if (Array.isArray(content) && content.some((b) => b && b.type === 'tool_result')) {
+      return { state: 'thinking', detail: '' };
+    }
+    const txt = typeof content === 'string' ? content : '';
+    return { state: 'thinking', detail: firstLine(txt) };
+  }
+
+  return { state: 'unknown', detail: '' };
+}
+
+function firstLine(s) {
+  if (!s) return '';
+  const line =
+    String(s)
+      .split('\n')
+      .find((l) => l.trim()) || '';
+  return line.trim().slice(0, 120);
+}
+
+module.exports = { projectsRoot, listSessionFiles, readTailObjects, summarizeSession };

package/lib/ui.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const { collectAgents } = require('./collect');
+const { buildFrame, sortAgents, SORTS } = require('./render');
+
+const ALT_ON = '\x1b[?1049h';
+const ALT_OFF = '\x1b[?1049l';
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const HOME = '\x1b[H';
+const CLEAR_BELOW = '\x1b[0J';
+
+const CTRL_C = String.fromCharCode(3);
+const ESC = String.fromCharCode(27);
+
+// Run the live, top-style dashboard until the user quits.
+function runLive(opts) {
+  const state = {
+    interval: opts.interval,
+    sort: opts.sort,
+    reverse: opts.reverse,
+  };
+
+  const out = process.stdout;
+  out.write(ALT_ON + HIDE_CURSOR);
+
+  let timer = null;
+  let stopped = false;
+
+  function cleanup() {
+    if (stopped) return;
+    stopped = true;
+    if (timer) clearInterval(timer);
+    if (process.stdin.isTTY) {
+      try {
+        process.stdin.setRawMode(false);
+      } catch (e) {
+        /* ignore */
+      }
+    }
+    process.stdin.pause();
+    out.write(SHOW_CURSOR + ALT_OFF);
+  }
+
+  function draw() {
+    const agents = sortAgents(collectAgents(), state.sort, state.reverse);
+    const frame = buildFrame(agents, {
+      width: out.columns,
+      height: out.rows,
+      interval: state.interval,
+      sort: state.sort,
+      reverse: state.reverse,
+      once: false,
+    });
+    out.write(HOME + frame + CLEAR_BELOW);
+  }
+
+  function reschedule() {
+    if (timer) clearInterval(timer);
+    timer = setInterval(draw, state.interval * 1000);
+  }
+
+  // Keyboard handling (raw mode).
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (data) => {
+      const key = data.toString();
+      if (key === CTRL_C || key === 'q' || key === ESC) {
+        cleanup();
+        process.exit(0);
+      } else if (key === 's') {
+        const i = SORTS.indexOf(state.sort);
+        state.sort = SORTS[(i + 1) % SORTS.length];
+        draw();
+      } else if (key === 'r') {
+        state.reverse = !state.reverse;
+        draw();
+      } else if (key === '+' || key === '=') {
+        state.interval = Math.min(60, state.interval + 1);
+        reschedule();
+        draw();
+      } else if (key === '-' || key === '_') {
+        state.interval = Math.max(1, state.interval - 1);
+        reschedule();
+        draw();
+      }
+    });
+  }
+
+  process.on('SIGINT', () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on('exit', cleanup);
+  out.on('resize', draw);
+
+  draw();
+  reschedule();
+}
+
+module.exports = { runLive };

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "agentop",
+  "version": "0.1.0",
+  "description": "top, but for your running Claude Code agents — a live terminal dashboard of every Claude CLI session on your machine.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "top",
+    "htop",
+    "monitor",
+    "cli",
+    "tui",
+    "agents",
+    "dashboard",
+    "anthropic"
+  ],
+  "homepage": "https://github.com/ktamas77/agentop#readme",
+  "bugs": {
+    "url": "https://github.com/ktamas77/agentop/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ktamas77/agentop.git"
+  },
+  "license": "MIT",
+  "author": "Tamas Kalman",
+  "type": "commonjs",
+  "bin": {
+    "agentop": "bin/agentop.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/agentop.js",
+    "test": "node --test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test",
+    "prepare": "husky"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.13.0",
+    "@types/node": "^22.8.0",
+    "eslint": "^9.13.0",
+    "eslint-config-prettier": "^9.1.0",
+    "globals": "^15.11.0",
+    "husky": "^9.1.6",
+    "lint-staged": "^15.2.10",
+    "prettier": "^3.3.3",
+    "typescript": "^5.6.3"
+  },
+  "lint-staged": {
+    "*.js": [
+      "prettier --write",
+      "eslint --fix"
+    ],
+    "*.{json,yml,yaml}": [
+      "prettier --write"
+    ]
+  }
+}