cctop

A keyboard-first menubar app to monitor and jump between AI coding sessions — minimum setup required.

Works with your existing editor and terminal. No IDE needed, no workflow changes — just install the app, connect your tools, and every session shows up in a floating panel you can navigate with your keyboard.

<table align="center"> <tr> <td align="center"><img src="docs/menubar-tokyonight-dark.png" alt="cctop menubar popup (Tokyo Night dark)" width="340"></td> <td align="center"><img src="docs/menubar-light.png" alt="cctop menubar popup (Claude light)" width="340"></td> </tr> <tr> <td align="center">Tokyo Night (dark)</td> <td align="center">Claude (light)</td> </tr> </table>

Features

At-a-glance status. A floating menubar panel shows all active sessions with color-coded badges: idle, working, waiting for input, waiting for permission, compacting. See the current prompt or tool in use (e.g. "Editing auth.ts") without switching windows.

Jump directly to any session. Click a session card to raise its VS Code, Cursor, or iTerm2 window — or stay on the keyboard. Arrow keys to browse, Enter to jump, Tab to switch tabs.

Draggable panel. Drag the header to reposition the panel anywhere on screen — position persists across launches. Double-click the header to snap back to the default menubar anchor.

Navigate mode. Hit a global hotkey to overlay numbered badges (1–9) on every session card, then press the number to jump instantly.

<img src="docs/menubar-navigate.png" alt="cctop navigate mode with numbered badges" width="340"> Navigate mode — press 1–9 to jump

Recent Projects. A second tab keeps session history so you can reopen past projects easily.

<img src="docs/menubar-recent.png" alt="cctop recent projects tab" width="340"> Recent projects tab

Smart status icon. See session health without opening the panel:

Status bar: A proportional bar next to the icon shows green (working), amber (needs input), red (permission pending), or gray (idle).
Attention tint: When any session needs your input, the icon shifts to terracotta — visible even in your peripheral vision.
Notch-aware: On MacBooks where the notch hides the menubar icon, a small status pill appears next to the camera so you always have a signal.

Supported Tools

| Tool | Status | How it connects | |------|--------|-----------------| | Claude Code | Supported | Shell hooks → cctop-hook CLI | | opencode | Supported | JS plugin → cctop-hook CLI | | pi | Supported | TS extension → cctop-hook CLI | | Codex CLI | Planned | Waiting for plugin/hook API to stabilize |

Themes

Four color schemes inspired by beloved developer tools — each with dark and light variants.

Switch themes in Settings > Appearance > Color.

Installation

Step 1: Install the app

Homebrew:

brew install --cask st0012/cctop/cctop

Or download the latest release — the app is signed and notarized by Apple.

Step 2: Connect your tools

Follow the app's instructions to connect your tools. The app auto-detects installed tools and offers one-click plugin installation.

Privacy

No network access. No analytics. No telemetry. All data stays on your machine.

cctop stores only:

Session status (idle / working / waiting)
Project directory name
Last activity timestamp
Current tool or prompt context

This data lives in ~/.cctop/sessions/ as plain JSON files. You can inspect it anytime:

ls ~/.cctop/sessions/
cat ~/.cctop/sessions/*.json | python3 -m json.tool

FAQ

Does cctop slow down my coding tool? No. The plugin calls a lightweight native binary (cctop-hook) on each event, which writes a small JSON file and returns immediately. There is no measurable impact on performance.

Do I need to configure anything per project? No. Once the plugin is installed, all sessions are automatically tracked. No per-project setup required.

Does it work with VS Code and Cursor? Yes. Clicking a session card focuses the correct project window.

Does it work with iTerm2? Yes. Clicking a session card raises the correct iTerm2 window, selects the tab, and focuses the pane — even with split panes or multiple windows.

[!NOTE] Requires macOS Automation permission. You'll be prompted to grant it on first use.

Does it work with Warp or other terminals? It activates the app but cannot target a specific terminal tab. You'll need to find the right tab manually.

How does cctop name sessions? By default, the project directory name (e.g. /path/to/my-app shows as "my-app"). In Claude Code, you can rename a session with /rename and cctop picks that up.

No sessions are showing up — what do I check? First, make sure you restarted sessions after installing the plugin. Then check if session files exist: ls ~/.cctop/sessions/. If the directory is empty, the plugin isn't writing data — verify it's installed correctly (see Step 2). If files exist but the menubar shows nothing, try restarting the cctop app.

What happens if a coding tool crashes? cctop detects dead sessions automatically. It checks whether each session's process is still running and removes stale entries. No manual cleanup needed.

Why does the app need to be in /Applications/? All plugins look for cctop-hook inside /Applications/cctop.app or ~/.cctop/bin/. Installing elsewhere breaks the hook path.

Uninstall

# Remove the menubar app
rm -rf /Applications/cctop.app

# Remove the Claude Code plugin
claude plugin remove cctop
claude plugin marketplace remove cctop

# Remove the opencode plugin
rm ~/.config/opencode/plugins/cctop.js

# Remove the pi extension
rm ~/.pi/agent/extensions/cctop.ts

# Remove session data and config
rm -rf ~/.cctop

If installed via Homebrew: brew uninstall --cask cctop

<details> <summary>How it works</summary>

All tools go through cctop-hook — a single native binary that manages all session state.

┌─────────────┐    hook fires     ┌────────────┐
│ Claude Code │ ────────────────> │ cctop-hook │ ──┐
│             │  SessionStart,    │  (Swift)   │   │
└─────────────┘  Stop, PreTool,…  └────────────┘   │
                                       ▲           │  writes JSON
┌─────────────┐   plugin event    ┌────┴───────┐   │  per-session
│  opencode   │ ────────────────> │ JS plugin  │   │
└─────────────┘  session.status,  │ (calls     │   │
                 tool.execute,…   │  cctop-hook│   │
┌─────────────┐                   └────────────┘   │
│     pi      │ ────────────────> ┌────────────┐   │
└─────────────┘  session_start,   │ TS ext     │ ──┤
                 tool_exec,…      │ (calls     │   ▼
                                  │  cctop-hook│  ┌───────────────────┐
                                  └────────────┘  │ ~/.cctop/sessions │
                                                  │   ├── 123.json    │
                                                  │   └── 456.json    │
                                                  └──────────┬────────┘
                                                             │ file watcher
                                                             ▼
                                                  ┌──────────────┐
                                                  │ Menubar app  │
                                                  │ (live status)│
                                                  └──────────────┘

Each tool has a thin plugin that translates events into cctop-hook calls
cctop-hook (Swift CLI) handles all session state and writes to ~/.cctop/sessions/
The menubar app watches this directory and displays live status
pi: non-interactive sessions (background agents) are automatically skipped

</details> <details> <summary>Build from source</summary>

Requires Xcode 16+ and macOS 13+.

git clone https://github.com/st0012/cctop.git
cd cctop
./scripts/bundle-macos.sh
cp -R dist/cctop.app /Applications/
open /Applications/cctop.app

</details>

License

MIT

Cctop

Install / Use

README