cctop Claude Code mod: a btop-style Claude Code dashboard in a side pane

cctop is a community mod by Thomas Stagl (tomstagl), the Claude Code plugin half of his cctop project, an htop/btop-style terminal dashboard for a running Claude Code session. The plugin draws that dashboard inside Claude Code itself, in a pane docked beside the transcript. Type /cctop-pane and it opens; type it again and it closes.

The pane has a view bar across its first row (cctop Coach Overview Tools Agents Files Events Advisor). Click a name to switch, or give the pane the keyboard with ctrl+x tab. According to the author's README, the views show:

• Coach: four lights, one nudge with [1 fill] [2 snooze] [3 why] buttons, and what is next.
• Overview: a header, six cells, an act line and one open body, the same "Console" layout as the standalone TUI.
• Tools: calls, errors, p50/p95 latency and tokens pushed into context, per tool.
• Agents: subagents, MCP servers and background tasks.
• Files: touched files, edits and re-reads.
• Events: a stream of tool, hook, permission, compaction, coach and cost events.
• Advisor: the current recommendation, plus what is queued and what is snoozed.

Context, cost and rate limits come from Claude Code's own $.session.usage(), so the pane already shows something with nothing else installed. The richer views are filled in by the separate cctop binary through cctop query. The plugin also ships two skills: /cctop, and cctop-insights, which lets Claude answer questions such as "what is filling my context?" by running cctop query.

The install block above adds the author's marketplace and installs the plugin from it. For the full dashboard, also install the cctop binary with brew install tomstagl/tap/cctop (or cargo install cctop), then restart Claude Code or run /reload-plugins.

The plugin is a single function-hooks module, plugin/hooks/pane.tsx, with a model reducer and one file per view. Every tool call is timed around next(e), and the result passes through untouched. This is from pane.tsx:

on('tool.call', async ($, e, next) => {
  const startedAt = await clockNow($);
  apply($, { type: 'tool.start', name: e.tool, at: startedAt });
  let result: ToolCallResult | undefined;
  try {
    result = await next(e);
    return result;
  } finally {
    apply($, {
      type: 'tool.end',
      name: e.tool,
      startedAt,
      at: await clockNow($),
      isError: result === undefined || result.isError === true,
      resultChars: result?.text?.length ?? 0,
    });
  }
}).catch(($, e, next) => {
  $.ui.log(`cctop: tool.call failed: ${next.error.message ?? next.error.kind}`);
  return next(e);
});

session.start registers /cctop-pane, runs a self-check (the clock returns a number, HOME is set, the session has an id), and runs cctop --version to find out whether the binary is installed. While the pane is open and the binary is present, a poller in poller.ts runs cctop query <verb> --session <id> --surface pane one verb at a time. It polls every 2 seconds while a turn runs and every 10 seconds when idle, and marks the data stale after 30 seconds without a successful round. Redraws are throttled to four a second. The pane remembers its open state and current view in $.store, so it comes back after a reload. It also re-reads the session id on every turn, so it keeps working after /clear.

There are no /config options. You choose the starting view with the command argument, /cctop-pane coach, /cctop-pane tools and so on, and /cctop-pane close closes the pane. The standalone repository ships colour themes (default dark and light, Catppuccin Mocha, Gruvbox, Nord, btop) for the binary's TUI. The pane itself uses Claude Code's own theme colours, so it follows light and dark mode.

We read every file the plugin can execute before running it: the hooks module, its views and the two skills. Here is what we found:

• Runs commands ($.process.run): only the cctop binary. It runs cctop --version, cctop query --help, cctop query <verb> --session <id> --surface pane, and cctop query coach --snooze <rule> when you press snooze. Each call is an argv array with no shell and a 3 to 5 second timeout. The plugin does not bundle the binary; you install it separately.
• Writes files ($.fs.write): one marker file per session, ~/.cctop/pane/<session-id>.json, holding the plugin version, the session id, whether the pane is open, and where it was drawn. Other cctop commands read it. $.fs.read reads only the plugin's own plugin.json, and $.env.get reads only HOME.
• Intercepts tool calls: the tool.call hook only measures timing and result length. It never changes or blocks a call, and its .catch passes the call on if the hook fails.
• Fills the prompt: the coach's [1 fill] button writes a suggested prompt into the input box with $.prompt.fill. It never submits it.
• No network in the plugin code, and no telemetry.

The /cctop skill tells Claude to ask you once whether to run cctop install --yes. The README says that command shows a diff of ~/.claude/settings.json and backs the file up before adding a status-line shim and hooks. That is the binary's behaviour, which we did not audit line by line; you can decline it. To turn the plugin off, run /plugin disable cctop.

The plugin loaded on Claude Code 2.1.291 on macOS, and claude plugin validate passed without warnings. The pane needs function hooks (Claude Code 2.1.269 or later). If the pane does not show up:

• Read the reply to /cctop-pane. It says whether the pane docked, was drawn above the prompt (terminal under 110 columns, or the classic renderer), or is hidden behind the /diff panel.
• "needs the cctop binary" means cctop is not on your PATH. The engine-only figures still work.
• With the binary installed, cctop pane status (run inside the session) lists each prerequisite with a fix.
• After installing from the shell into an open session, run /reload-plugins.

To check that it works after installing, open the pane with /cctop-pane, then send a short prompt that reads a file. The turn counter and the engine's context and rate-limit line update in the pane while the turn runs.