Cursor Top Quickstart

Get a live view of every Cursor agent on your machine in under a minute. The CLI is exposed as cursor-top and needs no native dependencies — only ps / PowerShell and the standard library.

Install

The plugin ships in the zoto-agents monorepo. From the repo root:

pnpm install
pnpm --filter @zoto-agents/zoto-cursor-top build

To use the CLI standalone, install the package globally (once published):

# with pnpm
pnpm add -g @zoto-agents/zoto-cursor-top
# or npm
npm install -g @zoto-agents/zoto-cursor-top

Run

Launch the interactive TUI, or pick a one-shot output mode:

cursor-top                # interactive live TUI (default 1s refresh)
cursor-top --demo         # synthetic fixture, no Cursor required
cursor-top --once         # render one frame to stdout and exit
cursor-top --json         # emit one snapshot as JSON and exit
cursor-top --interval 500 # refresh every 500ms (minimum 200ms)
cursor-top --lines 5      # tail 5 log lines per agent (default 3)
cursor-top --help         # show all flags

New to the tool? Start with cursor-top --demo — it renders a populated synthetic fixture so you can learn the layout without needing any Cursor session running.

Keyboard

Key	Action
`↑` / `↓` or `j` / `k`	Move selection.
`→` / `Enter` or `l`	Expand selected node.
`←` or `h`	Collapse selected node.
`e`	Expand all.
`c`	Collapse all.
`r`	Force refresh.
`q` or `Ctrl-C`	Quit.

Inside Cursor

Once the plugin is installed in Cursor, run the slash command to launch the TUI in the active terminal — any arguments are passed straight through to the CLI:

/zoto-cursor-top
/zoto-cursor-top --interval 500 --lines 5

The zoto-cursor-top-monitor skill provides a guided workflow for launching and interpreting the TUI — process discovery, hierarchy expansion, log-tail interpretation, and recommended flags for different scenarios.

Troubleshooting

If rows are missing or log tails come up empty, the zoto-cursor-top-troubleshooter agent diagnoses the gap. The most common case is a subagent appearing at root level — that always means the session metadata was missing a parentId, and the troubleshooter walks you through filing a Cursor-side report. See How the hierarchy is built on the Overview page.

Develop

From inside the plugin directory:

cd plugins/zoto-cursor-top
pnpm install
pnpm test           # vitest
pnpm validate       # structural validation
pnpm build          # tsup -> dist/cli.js
pnpm start          # run via tsx
pnpm demo           # run --demo via tsx