Sandbox
Sign in
@st0012/cctop
Tools#Claude Code#Codex#Any agent#Coding#Product

Menubar session tracker for AI coding tools

cctop is a macOS menubar app that shows live AI coding sessions, their status, and where to return to them. It connects to tools through local plugins and hooks, then uses that session data to jump you back to the right editor, terminal, or desktop thread.

150 stars•21 forks•Swift•Updated 11d ago
Who it's for

Builders who work across Claude Code, Codex, and other agent tools and want a fast way to track active sessions.

What it delivers

You can see which session is waiting on you and jump back to it with a keystroke instead of hunting through windows.

What it does

Live session tracking

Shows whether each session is working, idle, waiting, hidden, or ended.

Keyboard-first navigation

Lets you open navigate mode and jump to a session by pressing a number key.

Direct jump targets

Focuses the exact terminal tab, pane, workspace, or app when the target is known.

Worktree cleanup

Finds ended worktrees still on disk and checks Git state before offering removal.

Recent projects

Keeps session history so you can reopen past projects from the menubar.

Local-only storage

Writes session data as plain JSON under `~/.cctop/sessions/` with no analytics or upload.

How to get it

  1. 1Or use Homebrew
    brew install --cask st0012/cctop/cctop
  2. 2Claude setup
    claude plugin marketplace add st0012/cctop
  3. 3Then install the plugin
    claude plugin install cctop

README

cctop

Latest release  |  MIT license

Keep an eye on your AI coding sessions.

See which session is waiting on you. Jump back to the right tab, pane, thread, or project with a keystroke.

Download for Apple Silicon  |  Intel  |  Website

Animated preview of cctop tracking and jumping between AI coding sessions
One compact menubar view for sessions across tools.
Full launch video (MP4)

Why cctop

  • See at a glance which coding sessions are working, idle, or waiting on you.
  • Right-click to hide a session from cctop without stopping it or deleting its data. cctop asks first because you cannot show it again while its local session record exists.
  • Jump directly to the right editor window, terminal pane, desktop thread, or project.
  • Keep recent projects close without leaving a menubar app open all day.
  • Find leftover ended-session worktrees, check Git safety, and remove the ones you are done with.
  • Store session state locally as plain JSON. No analytics, telemetry, or session upload.

Works With Your Coding Tools

Each integration reports session events locally; cctop turns them into one menubar view and a reliable jump target.

Claude Code
Claude Code / Desktop
Claude plugin + event hooks 		OpenAI
Codex CLI / Desktop
Codex event hooks + trust step 		opencode
opencode
opencode plugin events 		pi
pi
pi extension events

Jump Support

When you click a session card, or use Navigate mode, cctop tries to take you to the most specific place it can.

Focus details and requirements
  • iTerm2, Ghostty, and Apple Terminal require macOS Automation permission.
  • Kitty targets the exact window when allow_remote_control socket-only and listen_on are enabled in kitty.conf; otherwise it falls back to app activation.
  • Warp targets the exact pane via its session deep link (WARP_FOCUS_URL), available since Warp v0.2026.05.27. Sessions started on older Warp versions fall back to app activation.
  • cmux targets the exact workspace surface from stored metadata, and can recover live cmux metadata for already-running sessions.
  • Ghostty requires version 1.3.0+ for AppleScript support. If the session TTY is unavailable, cctop falls back to working-directory matching.
  • Apple Terminal targets the tab by tty. Inside a multiplexer such as tmux or screen, it falls back to raising Terminal because the captured tty belongs to the multiplexer pane.
  • If cctop cannot find an exact target or app, it opens the project folder in Finder.

Designed For Scanning, Then Jumping

Navigate mode

Hit a global hotkey to overlay numbered badges on every session card, then press 1 to 9 to jump instantly.

 cctop navigate mode with numbered badges

Draggable panel

Drag the header anywhere on screen. cctop remembers the position, and double-clicking snaps it back to the menubar anchor.

 Dragging the cctop panel to a new position

Smart status icon

The menubar icon summarizes session health: healthy, needs attention, and a slim pill for laptops with a camera notch.

 Status icon states: all healthy, needs attention, and notch pill

Worktree cleanup

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.

 cctop cleanup tab listing ended worktrees with Git safety state

Recent projects

A second tab keeps session history so you can reopen past projects without hunting through old terminals.

 cctop recent projects tab

Install

1. Install the app

Download the latest signed and notarized build:

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.

Themes

Four palettes inspired by developer tools, each with light and dark variants. Switch themes in Settings > Appearance > Color.

ClaudeTokyo NightGruvboxNord
Claude dark theme screenshot Tokyo Night dark theme screenshot Gruvbox dark theme screenshot Nord dark theme screenshot

Privacy

No analytics, no telemetry, and no session upload. Session data stays on your machine in ~/.cctop/sessions/ as plain JSON.

cctop also publishes ~/.cctop/display-state.json for display integrations. Each session entry contains only the ordered display identity, name, status, and resolved color needed for the keys. The file also includes its schema version, generation time, and cctop process-liveness metadata. The Stream Deck plugin does not inspect session files or any Claude, Codex, opencode, or pi data.

Signed release builds use network access only for Sparkle update checks and downloads.

What cctop stores locally
  • Session status, such as idle, working, or waiting.
  • Project directory name.
  • Last activity timestamp.
  • Current tool or prompt context.

Inspect the files anytime:

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

The session-file fields are documented in docs/session-files.md.

FAQ

Does cctop slow down my coding tool?

No. Each integration calls the lightweight native helper (cctop-hook) on session events, writes a small JSON file, and returns immediately.

Do I need to configure anything per project?

No. Once your tools are connected, new sessions are automatically tracked.

How does cctop name sessions?

By default, cctop uses the project directory name. 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, restart sessions after installing the plugin or hooks. Then check whether session files exist:

ls ~/.cctop/sessions/

If the directory is empty, the integration is not writing data yet. If files exist but the menubar shows nothing, check whether those JSON files have "hidden": true, then try restarting cctop.

Why do some archived desktop sessions not appear in Cleanup?

Some desktop clients remove their managed worktree when you archive a session. In that case, there is nothing left for cctop to remove, so Cleanup stays quiet. Cleanup is most useful for CLI and manual-worktree sessions where the linked Git worktree remains on disk after the session ends.

Why does Codex Desktop need an extra trust step?

Codex only runs hooks you have explicitly reviewed and trusted. cctop can install the hooks, but Codex Desktop does not currently surface the hook-review prompt. Start one Codex CLI session in a terminal and trust the hooks there; Codex Desktop shares that trust state.

What happens if a coding tool crashes?

cctop detects dead sessions automatically by checking whether each session's process is still running, then removes stale entries.

Why does the app need to live in /Applications?

Plugins look for cctop-hook inside /Applications/cctop.app, ~/Applications/cctop.app, or ~/.cctop/bin/. Installing elsewhere breaks the hook path.

I am on an Intel Mac and the updater installed the wrong architecture.

cctop releases up to and including v0.15.2 shipped an appcast that confused Sparkle's update picker, so Intel Macs could receive the Apple Silicon build. The fix is in place going forward, but installed copies of cctop v0.15.2 and older may need one manual replacement:

  1. Quit cctop.
  2. Download cctop-macOS-x86_64.dmg.
  3. Drag the new cctop.app into /Applications/, replacing the existing one.
  4. Relaunch cctop. Future updates will pick the correct architecture.

Reference

How it works

All integrations call cctop-hook, a single native helper that owns session state.

flowchart LR
  tools["Claude / Codex / opencode / pi"] --> hook["cctop-hook"]
  hook --> files["~/.cctop/sessions/*.json"]
  files --> app["cctop menubar app"]
  1. A tool plugin or hook translates client events into cctop-hook calls.
  2. cctop-hook writes one small JSON file per session.
  3. The menubar app watches ~/.cctop/sessions/ and renders live status.
  4. pi skips non-interactive background sessions automatically.
Uninstall 
# Remove the menubar app
rm -rf /Applications/cctop.app

# Remove the Claude Code / Claude Desktop 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 the Codex CLI / Codex Desktop hooks
rm ~/.codex/cctop-shim.sh
# Then remove cctop entries from ~/.codex/hooks.json

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

If installed via Homebrew:

brew uninstall --cask cctop
Build from source

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

License

MIT

Files in the repo

Repository payload•27 top-level entries
  • .agents
  • .claude
  • .claude-plugin
  • .github
  • .xcodebuildmcp
  • assets
  • docs
  • fixtures
  • menubar
  • packaging
  • plugins
  • script
  • scripts
  • site
  • video
  • .gitignore
  • .swiftlint.yml
  • AGENTS.md
  • appcast.xml
  • CLAUDE.md
  • CONTRIBUTING.md
  • DESIGN.md
  • hook-input.schema.json
  • LICENSE
  • Makefile
  • PRODUCT.md
  • README.md

Discussion (0)

Ask about usage, or say what you built with it

Sign in to join the discussion.

No comments yet. Be the first to say what this is good for.

More tools

JuliusBrussee/
caveman
JuliusBrussee/cavemanTools

🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman

105k
1 add
MemPalace/
mempalace
MemPalace/mempalaceTools

The best-benchmarked open-source AI memory system. And it's free.

59k
stablyai/
orca
stablyai/orcaTools

Orca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

66k
farion1231/cc-switchTools

A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io

132k
diegosouzapw/OmniRouteTools

Never stop coding. Free MIT AI gateway: one endpoint, 352 providers (150+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors

64k
headroomlabs-ai/
headroom
headroomlabs-ai/headroomTools

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

71k