Cmux Agent Sidebar — Development skill for Claude Code

cmux-agent-sidebar

A custom sidebar for [cmux](https://cmux.com) that shows, at a glance, which of your **Claude Code** and **Codex** sessions are running, waiting for you, or done, plus colored, icon-tagged workspace groups.

[中文说明](README.zh-CN.md)

 ▾ 💼 Work
   ┃ API refactor              Running
   ┃ Release notes             Done •
 ▾ ▶️ Content
   ┃ Video script              Needs you
 ▸  Code

What it does

• Status pill per workspace: Needs you > Running > Done > Idle.
  • Watches every terminal pane in a workspace (splits and tabs), so a Claude Code pane and a Codex pane side by side are both covered. If any pane is running, the workspace is running.
  • Recognizes Claude Code's spinner (including Waiting for N background agent and running subagent rows) and Codex's • Working (12s • esc to interrupt) status line.
  • Needs you when a permission prompt or option menu is on screen.
  • Done (with a red dot) when an agent just finished in a workspace you haven't looked at yet.
• Colored groups: group headers get the group's color and an SF Symbol icon; every row in a group gets a rail in that color.
• Keeps everything from cmux's built-in workspaces sidebar: drag between groups, multi-select, inline rename, context menus.

Why read the screen?

cmux's built-in agent hooks drift: Claude's 60-second idle reminder reads as "waiting for input", and a session interrupted with Esc can stay "running". A small daemon (`daemon/agent_status.py`) instead reads each pane every 2 seconds with `cmux read-screen` and writes the result into the workspace status lane.

It only looks at fixed UI positions (the spinner line right above the input box, the hints below it, the last lines of a dialog), never at the conversation text, so an agent *talking about* "esc to interrupt" doesn't flip the status.

Requirements

• macOS with cmux 0.65 or later (custom sidebars beta)
• python3 (comes with the Xcode comm