Skip to content
Back to search

cctop

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/st0012--cctop/badge.svg)](/listings/st0012--cctop)

HTML

<a href="/listings/st0012--cctop"><img src="/api/listings/st0012--cctop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the app

Download the latest signed and notarized build:

- [Apple Silicon](https://github.com/st0012/cctop/releases/latest/download/cctop-macOS-arm64.dmg) - [Intel](https://github.com/st0012/cctop/releases/latest/download/cctop-macOS-x86_64.dmg)

Or use Homebrew:

brew install --cask st0012/cctop/cctop

cctop runs on macOS 13+. Signed release builds can check for updates through Sparkle.

2. Connect your tools

Open **Settings**. cctop shows setup actions for detected coding clients under **Tools**, and companion apps under **Integrations**:

- Claude Code / Claude Desktop: click **Copy Install Command**, then run the two commands below in a terminal. - opencode and pi: click **Install Plugin**. - Stream Deck: under **Integrations**, click **Install Plugin**. Stream Deck offers cctop's optional default profile for compatible 15-key Stream Decks; it adds the first five sessions across the top row and **Toggle Panel** at row 2, column 1 without switching away from your current profile. If you skip that prompt, use **Import default profile** later or place the Session and Toggle Panel actions manually on any supported model. To show more sessions, add Session actions and set their slots to 6, 7, and so on. - Codex CLI / Codex Desktop: click **Install Hooks**, then start a new Codex CLI session and choose **Trust all and continue** when Codex reviews the hooks. Codex Desktop shares that trust state.

Claude setup:

claude plugin marketplace add st0012/cctop

Then install the plugin:

claude plugin install cctop

Restart any running sessions to pick up newly installed hooks or plugins.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "cctop",
  3. "owner": {
  4. "name": "Stan Lo",
  5. "email": "stan001212@gmail.com"
  6. },
  7. "metadata": {
  8. "description": "AI coding session monitor",
  9. "version": "0.21.4"
  10. },
  11. "plugins": [
  12. {
  13. "name": "cctop",
  14. "source": "./plugins/cctop",
  15. "description": "Monitor and navigate Claude Code sessions across workspaces",
  16. "version": "0.21.4"
  17. }
  18. ]
  19. }
README.md · README · 438 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # cctop
  2. <p>
  3. <a href="https://github.com/st0012/cctop/releases/latest">Latest release</a>
  4. &nbsp;|&nbsp;
  5. <a href="LICENSE">MIT license</a>
  6. </p>
  7. **Keep an eye on your AI coding sessions.**
  8. See which session is waiting on you. Jump back to the right tab, pane, thread, or
  9. project with a keystroke.
  10. <p>
  11. <a href="https://github.com/st0012/cctop/releases/latest/download/cctop-macOS-arm64.dmg"><strong>Download for Apple Silicon</strong></a>
  12. &nbsp;|&nbsp;
  13. <a href="https://github.com/st0012/cctop/releases/latest/download/cctop-macOS-x86_64.dmg">Intel</a>
  14. &nbsp;|&nbsp;
  15. <a href="https://cctop.app">Website</a>
  16. </p>
  17. <p align="center">
  18. <img src="https://github.com/st0012/cctop/releases/download/media-assets/cctop-launch-preview.avif" alt="Animated preview of cctop tracking and jumping between AI coding sessions" width="780">
  19. <br>
  20. <em>One compact menubar view for sessions across tools.</em>
  21. <br>
  22. <a href="https://github.com/st0012/cctop/releases/download/media-assets/cctop-launch.mp4">Full launch video (MP4)</a>
  23. </p>
  24. ## Why cctop
  25. - See at a glance which coding sessions are working, idle, or waiting on you.
  26. - Right-click to hide a session from cctop without stopping it or deleting its data.
  27. cctop asks first because you cannot show it again while its local session record exists.
  28. - Jump directly to the right editor window, terminal pane, desktop thread, or project.
  29. - Keep recent projects close without leaving a menubar app open all day.
  30. - Find leftover ended-session worktrees, check Git safety, and remove the ones
  31. you are done with.
  32. - Store session state locally as plain JSON. No analytics, telemetry, or session upload.
  33. ## Works With Your Coding Tools
  34. Each integration reports session events locally; cctop turns them into one menubar
  35. view and a reliable jump target.
  36. <table>
  37. <tr>
  38. <td align="center" width="25%">
  39. <a href="https://code.claude.com/docs">
  40. <img src="assets/icons/claude-code.svg" alt="Claude Code" height="36"><br>
  41. <strong>Claude Code / Desktop</strong>
  42. </a>
  43. <br><sub>Claude plugin + event hooks</sub>
  44. </td>
  45. <td align="center" width="25%">
  46. <a href="https://developers.openai.com/codex">
  47. <img src="assets/icons/openai.svg" alt="OpenAI" height="36"><br>
  48. <strong>Codex CLI / Desktop</strong>
  49. </a>
  50. <br><sub>Codex event hooks + trust step</sub>
  51. </td>
  52. <td align="center" width="25%">
  53. <a href="https://opencode.ai">
  54. <img src="assets/icons/opencode.svg" alt="opencode" height="28"><br>
  55. <strong>opencode</strong>
  56. </a>
  57. <br><sub>opencode plugin events</sub>
  58. </td>
  59. <td align="center" width="25%">
  60. <a href="https://pi.dev/">
  61. <img src="assets/icons/pi.svg" alt="pi" height="36"><br>
  62. <strong>pi</strong>
  63. </a>
  64. <br><sub>pi extension events</sub>
  65. </td>
  66. </tr>
  67. </table>
  68. ## Jump Support
  69. When you click a session card, or use Navigate mode, cctop tries to take you to
  70. the most specific place it can.
  71. - **Targets the exact session:** [iTerm2](https://iterm2.com/), [Warp](https://www.warp.dev/terminal), [cmux](https://cmux.com/), [Kitty](https://sw.kovidgoyal.net/kitty/), [Ghostty](https://ghostty.org/), [Terminal](https://support.apple.com/guide/terminal/welcome/mac), [Codex Desktop](https://developers.openai.com/codex/app), [Herdr](https://github.com/ogulcancelik/herdr), [Zellij](https://zellij.dev/), [tmux](https://tmux.us/). cctop jumps to the right window, tab, pane, surface, or desktop thread.
  72. - **Opens the project:** [VS Code](https://code.visualstudio.com/), [Cursor](https://cursor.com/), [Windsurf](https://windsurf.com/download), [Zed](https://zed.dev/). cctop focuses the editor window, using the workspace file if present.
  73. - **Activates the app:** [Claude Desktop](https://claude.com/download) and other detected macOS apps. cctop brings the app to the front so you can find the tab manually.
  74. <details>
  75. <summary>Focus details and requirements</summary>
  76. - iTerm2, Ghostty, and Apple Terminal require macOS Automation permission.
  77. - Kitty targets the exact window when `allow_remote_control socket-only` and
  78. `listen_on` are enabled in `kitty.conf`; otherwise it falls back to app
  79. activation.
  80. - Warp targets the exact pane via its session deep link
  81. ([`WARP_FOCUS_URL`](https://github.com/warpdotdev/warp/pull/11130)), available
  82. since Warp v0.2026.05.27. Sessions started on older Warp versions fall back to
  83. app activation.
  84. - cmux targets the exact workspace surface from stored metadata, and can recover
  85. live cmux metadata for already-running sessions.
  86. - Ghostty requires version 1.3.0+ for AppleScript support. If the session TTY is
  87. unavailable, cctop falls back to working-directory matching.
  88. - Apple Terminal targets the tab by tty. Inside a multiplexer such as tmux or
  89. screen, it falls back to raising Terminal because the captured tty belongs to
  90. the multiplexer pane.
  91. - If cctop cannot find an exact target or app, it opens the project folder in Finder.
  92. </details>
  93. ## Designed For Scanning, Then Jumping
  94. <table>
  95. <tr>
  96. <td width="42%">
  97. <h3>Navigate mode</h3>
  98. <p>Hit a global hotkey to overlay numbered badges on every session card, then press <kbd>1</kbd> to <kbd>9</kbd> to jump instantly.</p>
  99. </td>
  100. <td align="center">
  101. <img src="docs/menubar-navigate.png" alt="cctop navigate mode with numbered badges" width="300">
  102. </td>
  103. </tr>
  104. <tr>
  105. <td width="42%">
  106. <h3>Draggable panel</h3>
  107. <p>Drag the header anywhere on screen. cctop remembers the position, and double-clicking snaps it back to the menubar anchor.</p>
  108. </td>
  109. <td align="center">
  110. <img src="docs/draggable-panel-demo.gif" alt="Dragging the cctop panel to a new position" width="430">
  111. </td>
  112. </tr>
  113. <tr>
  114. <td width="42%">
  115. <h3>Smart status icon</h3>
  116. <p>The menubar icon summarizes session health: healthy, needs attention, and a slim pill for laptops with a camera notch.</p>
  117. </td>
  118. <td align="center">
  119. <img src="docs/status-icon.png" alt="Status icon states: all healthy, needs attention, and notch pill" width="430">
  120. </td>
  121. </tr>
  122. <tr>
  123. <td width="42%">
  124. <h3>Worktree cleanup</h3>
  125. <p>Cleanup finds ended agent worktrees that still exist on disk, especially CLI or manual worktree runs. cctop checks Git state before offering the right remove action.</p>
  126. </td>
  127. <td align="center">
  128. <img src="docs/menubar-cleanup.png" alt="cctop cleanup tab listing ended worktrees with Git safety state" width="300">
  129. </td>
  130. </tr>
  131. <tr>
  132. <td width="42%">
  133. <h3>Recent projects</h3>
  134. <p>A second tab keeps session history so you can reopen past projects without hunting through old terminals.</p>
  135. </td>
  136. <td align="center">
  137. <img src="docs/menubar-recent.png" alt="cctop recent projects tab" width="300">
  138. </td>
  139. </tr>
  140. </table>
  141. ## Install
  142. ### 1. Install the app
  143. Download the latest signed and notarized build:
  144. - [Apple Silicon](https://github.com/st0012/cctop/releases/latest/download/cctop-macOS-arm64.dmg)
  145. - [Intel](https://github.com/st0012/cctop/releases/latest/download/cctop-macOS-x86_64.dmg)
  146. Or use Homebrew:
  147. ```bash
  148. brew install --cask st0012/cctop/cctop
  149. ```
  150. cctop runs on macOS 13+. Signed release builds can check for updates through
  151. Sparkle.
  152. ### 2. Connect your tools
  153. Open **Settings**. cctop shows setup actions for detected coding clients under
  154. **Tools**, and companion apps under **Integrations**:
  155. - Claude Code / Claude Desktop: click **Copy Install Command**, then run the
  156. two commands below in a terminal.
  157. - opencode and pi: click **Install Plugin**.
  158. - Stream Deck: under **Integrations**, click **Install Plugin**. Stream Deck
  159. offers cctop's optional default profile for compatible 15-key Stream Decks; it
  160. adds the first five sessions across the top row and **Toggle Panel** at row 2,
  161. column 1 without switching away from your current profile. If you skip that
  162. prompt, use **Import default profile** later or place the Session and Toggle
  163. Panel actions manually on any supported model. To show more sessions, add
  164. Session actions and set their slots to 6, 7, and so on.
  165. - Codex CLI / Codex Desktop: click **Install Hooks**, then start a new Codex CLI
  166. session and choose **Trust all and continue** when Codex reviews the hooks.
  167. Codex Desktop shares that trust state.
  168. Claude setup:
  169. ```bash
  170. claude plugin marketplace add st0012/cctop
  171. ```
  172. Then install the plugin:
  173. ```bash
  174. claude plugin install cctop
  175. ```
  176. Restart any running sessions to pick up newly installed hooks or plugins.
  177. ## Themes
  178. Four palettes inspired by developer tools, each with light and dark variants.
  179. Switch themes in **Settings > Appearance > Color**.
  180. <table>
  181. <tr>
  182. <th align="center">Claude</th>
  183. <th align="center">Tokyo Night</th>
  184. <th align="center">Gruvbox</th>
  185. <th align="center">Nord</th>
  186. </tr>
  187. <tr>
  188. <td align="center">
  189. <img src="docs/theme-claude-dark.png" alt="Claude dark theme screenshot" width="180">
  190. </td>
  191. <td align="center">
  192. <img src="docs/theme-tokyoNight-dark.png" alt="Tokyo Night dark theme screenshot" width="180">
  193. </td>
  194. <td align="center">
  195. <img src="docs/theme-gruvbox-dark.png" alt="Gruvbox dark theme screenshot" width="180">
  196. </td>
  197. <td align="center">
  198. <img src="docs/theme-nord-dark.png" alt="Nord dark theme screenshot" width="180">
  199. </td>
  200. </tr>
  201. </table>
  202. ## Privacy
  203. **No analytics, no telemetry, and no session upload.** Session data stays on your
  204. machine in `~/.cctop/sessions/` as plain JSON.
  205. cctop also publishes `~/.cctop/display-state.json` for display integrations.
  206. Each session entry contains only the ordered display identity, name, status,
  207. and resolved color needed for the keys. The file also includes its schema
  208. version, generation time, and cctop process-liveness metadata. The Stream Deck
  209. plugin does not inspect session files or any Claude, Codex, opencode, or pi data.
  210. Signed release builds use network access only for Sparkle update checks and
  211. downloads.
  212. <details>
  213. <summary>What cctop stores locally</summary>
  214. - Session status, such as idle, working, or waiting.
  215. - Project directory name.
  216. - Last activity timestamp.
  217. - Current tool or prompt context.
  218. Inspect the files anytime:
  219. ```bash
  220. ls ~/.cctop/sessions/
  221. cat ~/.cctop/sessions/*.json | python3 -m json.tool
  222. ```
  223. The session-file fields are documented in
  224. [`docs/session-files.md`](docs/session-files.md).
  225. </details>
  226. ## FAQ
  227. <details>
  228. <summary>Does cctop slow down my coding tool?</summary>
  229. No. Each integration calls the lightweight native helper (`cctop-hook`) on
  230. session events, writes a small JSON file, and returns immediately.
  231. </details>
  232. <details>
  233. <summary>Do I need to configure anything per project?</summary>
  234. No. Once your tools are connected, new sessions are automatically tracked.
  235. </details>
  236. <details>
  237. <summary>How does cctop name sessions?</summary>
  238. By default, cctop uses the project directory name. In Claude Code, you can rename
  239. a session with `/rename` and cctop picks that up.
  240. </details>
  241. <details>
  242. <summary>No sessions are showing up. What do I check?</summary>
  243. First, restart sessions after installing the plugin or hooks. Then check whether
  244. session files exist:
  245. ```bash
  246. ls ~/.cctop/sessions/
  247. ```
  248. If the directory is empty, the integration is not writing data yet. If files
  249. exist but the menubar shows nothing, check whether those JSON files have
  250. `"hidden": true`, then try restarting cctop.
  251. </details>
  252. <details>
  253. <summary>Why do some archived desktop sessions not appear in Cleanup?</summary>
  254. Some desktop clients remove their managed worktree when you archive a session.
  255. In that case, there is nothing left for cctop to remove, so Cleanup stays quiet.
  256. Cleanup is most useful for CLI and manual-worktree sessions where the linked Git
  257. worktree remains on disk after the session ends.
  258. </details>
  259. <details>
  260. <summary>Why does Codex Desktop need an extra trust step?</summary>
  261. Codex only runs hooks you have explicitly reviewed and trusted. cctop can
  262. install the hooks, but Codex Desktop does not currently surface the hook-review
  263. prompt. Start one Codex CLI session in a terminal and trust the hooks there;
  264. Codex Desktop shares that trust state.
  265. </details>
  266. <details>
  267. <summary>What happens if a coding tool crashes?</summary>
  268. cctop detects dead sessions automatically by checking whether each session's
  269. process is still running, then removes stale entries.
  270. </details>
  271. <details>
  272. <summary>Why does the app need to live in /Applications?</summary>
  273. Plugins look for `cctop-hook` inside `/Applications/cctop.app`,
  274. `~/Applications/cctop.app`, or `~/.cctop/bin/`. Installing elsewhere breaks the
  275. hook path.
  276. </details>
  277. <details>
  278. <summary>I am on an Intel Mac and the updater installed the wrong architecture.</summary>
  279. cctop releases up to and including v0.15.2 shipped an appcast that confused
  280. Sparkle's update picker, so Intel Macs could receive the Apple Silicon build.
  281. The fix is in place going forward, but installed copies of cctop v0.15.2 and
  282. older may need one manual replacement:
  283. 1. Quit cctop.
  284. 2. Download [`cctop-macOS-x86_64.dmg`](https://github.com/st0012/cctop/releases/latest/download/cctop-macOS-x86_64.dmg).
  285. 3. Drag the new `cctop.app` into `/Applications/`, replacing the existing one.
  286. 4. Relaunch cctop. Future updates will pick the correct architecture.
  287. </details>
  288. ## Reference
  289. <details>
  290. <summary>How it works</summary>
  291. All integrations call `cctop-hook`, a single native helper that owns session
  292. state.
  293. ```mermaid
  294. flowchart LR
  295. tools["Claude / Codex / opencode / pi"] --> hook["cctop-hook"]
  296. hook --> files["~/.cctop/sessions/*.json"]
  297. files --> app["cctop menubar app"]
  298. ```
  299. 1. A tool plugin or hook translates client events into `cctop-hook` calls.
  300. 2. `cctop-hook` writes one small JSON file per session.
  301. 3. The menubar app watches `~/.cctop/sessions/` and renders live status.
  302. 4. pi skips non-interactive background sessions automatically.
  303. </details>
  304. <details>
  305. <summary>Uninstall</summary>
  306. ```bash
  307. # Remove the menubar app
  308. rm -rf /Applications/cctop.app
  309. # Remove the Claude Code / Claude Desktop plugin
  310. claude plugin remove cctop
  311. claude plugin marketplace remove cctop
  312. # Remove the opencode plugin
  313. rm ~/.config/opencode/plugins/cctop.js
  314. # Remove the pi extension
  315. rm ~/.pi/agent/extensions/cctop.ts
  316. # Remove the Codex CLI / Codex Desktop hooks
  317. rm ~/.codex/cctop-shim.sh
  318. # Then remove cctop entries from ~/.codex/hooks.json
  319. # Remove session data and config
  320. rm -rf ~/.cctop
  321. ```
  322. If installed via Homebrew:
  323. ```bash
  324. brew uninstall --cask cctop
  325. ```
  326. </details>
  327. <details>
  328. <summary>Build from source</summary>
  329. Requires Xcode 16+ and macOS 13+.
  330. ```bash
  331. git clone https://github.com/st0012/cctop.git
  332. cd cctop
  333. ./scripts/bundle-macos.sh
  334. cp -R dist/cctop.app /Applications/
  335. open /Applications/cctop.app
  336. ```
  337. </details>
  338. ## License
  339. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.