Cursor Top

A live, htop-style CLI that shows every Cursor agent on the current machine. The zoto-cursor-top plugin discovers Cursor IDE windows, every cursor-agent CLI session, and Cloud Agent VM exec daemons, then renders them in one expandable tree. Parent agents expand to reveal their subagents, and every row shows the start time, elapsed duration, model, repo (working directory), status, and the last few log lines scrolling live.

cursor-top  ·  5 processes · 3 roots · 5 subagents · refresh 1000ms

TYPE     PID  AGENT                                MODEL              REPO                     START (elapsed)  STATUS
[CLD]   6712  ▼ Cloud Agent VM                     claude-sonnet-4.5  /workspace               11:30:14 (32m04s) running
              Design plugin live-updating htop CLI
              log: tool: write plugins/zoto-cursor-top/src/cli.ts
              log: spawning subagent: generalPurpose
              log: tool: glob 'plugins/**/.cursor-plugin/plugin.json'
   [SUB]   --  ▶ Task(explore)                     claude-sonnet-4.5  /workspace               11:32:01 (30m17s) done
   [SUB]   --  ▼ Task(generalPurpose)              claude-sonnet-4.5  /workspace               11:40:01 (22m17s) running
              Scaffold htop-style TUI and wire discovery layer
              log: vitest 18/18 passed
              log: tsup build dist/cli.js ... 142kb
              log: writing tests/discovery/processes.test.ts
   [SUB]   --  ▶ Task(debug)                       claude-sonnet-4.5  /workspace               11:58:01 (4m17s)  waiting
[IDE]   4231  ▶ Cursor IDE                         claude-opus-4.7    /Users/dev/work/app      12:01:11 (14m07s) running
[CLI]   5612  ▶ cursor-agent CLI                   gpt-5              /Users/dev/work/util     12:08:11 (7m07s)  waiting

[↑/↓] move  [→/enter] expand  [←] collapse  [e]xpand all  [c]ollapse all  [r]efresh  [q]uit

A populated --demo frame. Cloud, IDE, and CLI roots sit at the top level; Task subagents nest under their parent.

When to use

Reach for Cursor Top when you want to:

See, in one glance, every Cursor agent running across your machine — IDE, CLI, and Cloud.
Understand the parent-to-subagent hierarchy of a long-running, multi-agent task.
Tail the most recent log lines of several agents at once without switching windows.
Capture a machine-readable snapshot (--json) or a one-shot frame (--once) for a report or CI log.

Features

Feature	What it does
Cross-process visibility	Discovers Cursor IDE windows, every `cursor-agent` CLI session, and Cloud Agent VM exec daemons in one view.
Parent / subagent hierarchy	Subagents spawned via the `Task` tool are nested under their parent in a collapsible tree.
Per-row context	Start time, elapsed duration, model, repo, status, and the last 3 log lines (configurable) for every agent.
Live updates	Refresh interval is configurable — default 1 second, minimum 200ms. Log lines re-tail every tick.
Three output modes	Interactive TUI, `--once` for a one-shot formatted frame, and `--json` for machine-readable snapshots.
Demo mode	`--demo` renders a populated synthetic fixture for screenshots and onboarding — no Cursor session required.
No native deps	Works on macOS, Linux, and Windows using only `ps` / PowerShell and the standard library.

Data sources

Every data source is optional: the CLI tolerates missing directories and emits diagnostics rather than crashing.

Source	Used for
`ps -axww` (macOS / Linux) or `Get-CimInstance Win32_Process` (Windows)	Cursor IDE, `cursor-agent`, and Cloud Agent VM processes.
`~/Library/Application Support/Cursor/` (macOS), `~/.config/Cursor/` (Linux), `%APPDATA%/Cursor/` (Windows)	IDE session metadata.
`~/.cursor/cli/`	`cursor-agent` CLI session metadata.
`~/.cursor/projects/<workspace>/`	Cloud Agent VM in-flight agents.
Log files referenced from each session record	Last few lines per agent.

How the hierarchy is built

Explicit parentId from session metadata wins when present.
PID → PPID from the OS process table is used when metadata is missing.
Root fallback — any node with no resolvable parent is rendered at the top level.

A subagent appearing at root level always indicates that the session metadata was missing a parentId for it. The zoto-cursor-top-troubleshooter agent walks you through filing a Cursor-side report when this happens.

Inside Cursor

Beyond the standalone CLI, the plugin registers:

The slash command /zoto-cursor-top — launches the TUI in the active terminal with $ARGUMENTS passed through.
The skill zoto-cursor-top-monitor — a guided workflow for launching and interpreting the TUI.
The agent zoto-cursor-top-troubleshooter — diagnoses missing rows or empty log tails when discovery comes up short.
The rule zoto-cursor-top.mdc — documents conventions and data sources for any agent that wants to invoke or describe the CLI.