Using ClawLight CLI
The TUI dashboard, the macOS menu-bar indicator, what each status color means, and the per-agent badges.
The ClawLight CLI gives you two ways to watch your sessions: a full terminal dashboard and an always-on menu-bar icon. Both read the same live session state.
The TUI dashboard
Launch the interactive dashboard:
clawlightYou'll see every active Claude Code, opencode, Codex CLI, and GitHub Copilot CLI session with:
- An auto-generated name derived from the session's initial prompt
- A small badge (
oc/cx/co) if the session isn't Claude Code. See supported agents for the full legend - Its current status color
- Live updates as session state changes on disk
The menu-bar daemon
The daemon shows a single color-coded icon in your macOS menu bar that aggregates all of your sessions into one status:
clawlight menubarIf you ran clawlight install, this is already set up to run automatically at
login — running it by hand is only needed for debugging.
What the colors mean
The Claw Light hardware shows exactly these colors — so anything you learn here applies to the lamp on your desk.
| Color | State | What's happening |
|---|---|---|
| 🟢 Green | Active | One or more sessions are actively working. |
| 🟡 Yellow | Idle | Sessions exist but nothing is running. |
| 🔴 Red | Needs help | A session is waiting for your input. |
| ⚪ Gray | No sessions | Nothing is live. |
The aggregate rule is "most urgent wins": if any session needs you, the icon is red, even if others are still working.
Real-time updates
The ClawLight CLI watches its shared state directory for changes, so status updates are event-driven rather than polled across every agent it's set up. The icon (and your Claw Light) flips within a moment of a session changing state.
Next: supported agents →