\n \n
\n\n\n\n---\n\n## Install\n\n```bash\nnpx -y sessions-dashboard install\n```\n\nRequires Node β₯18 on PATH. The installer auto-detects which of the three CLIs are on your PATH and registers `sessions-dashboard` with each. First run pre-fetches Playwright's Chromium (~150 MB).\n\nAfter install, restart your CLI(s) and ask any session: *\"Open the sessions dashboard\"*\n\nTo remove the MCP registrations later: `npx -y sessions-dashboard uninstall`.\n\nFor installing from source (contributors), per-CLI manual config, and platform-specific caveats (Codex on Windows / Limited persistence mode), see [docs/INSTALL.md](docs/INSTALL.md).\n\n---\n\n## Why\n\nIf you run more than one CLI agent at a time, you quickly lose track:\n\n- Which session is working on what repo?\n- Which of my dozen terminal tabs is the session I need?\n- Is session 3 actively working right now, or idle waiting for you?\n- What tool is that long-running session stuck on?\n- How do I group related sessions (e.g. frontend + backend workers) visually?\n\n`sessions-dashboard` gives you a live, at-a-glance view:\n\n- π’ **`working`** β the agent is producing output right now\n- π£ **`running bash..`** β a tool is executing (you see which one)\n- βͺ **`idle 2m`** β done, waiting for your next prompt\n- **Drag-and-drop groups** β organize sessions into named columns that persist across restarts\n- **One-click focus (macOS, Windows + WezTerm)** β jump from a card to the corresponding terminal tab, ready to prompt.\n- **Shared browser** β any session can open a webview every other session can script (useful for coordinated debugging)\n\n---\n\n## Quick tour\n\n### Open the dashboard\n\nAny session can open it:\n\n> *\"Open the sessions dashboard\"*\n\nA Chromium window appears, polling the daemon every 2 s. Every session currently using `sessions-dashboard` (or set to auto-register β see [Configuration](#configuration)) shows up as a card.\n\n### Activity indicator\n\nEach card shows a live pill:\n\n| Pill | Meaning |\n|---|---|\n| π’ `working` | The agent is producing output β text, thinking tokens, or about to dispatch a tool |\n| π£ `running bash..`, `running sessions-dashboardΒ·screenshot..` | A tool is executing. The tool name is surfaced |\n| βͺ `idle 2m` | Assistant finished its turn, waiting for your next prompt |\n\nThe state is derived from each session's transcript (tail-state tracking against the host CLI's chat log). Long-running tools stay accurately marked as `running` β no 60-second false-idle.\n\n### Name your sessions\n\nSessions default to their cwd's basename. Give them nicer names three ways:\n\n- **Env var before launching:** `SESSIONS_DASHBOARD_SESSION_NAME=frontend-worker claude` (works for any host; `CLAUDE_SESSION_NAME` is a Claude-era alias)\n- **`/rename` slash command** inside the session β auto-picked up within 15 s. Supported in Claude Code and Codex CLI; **Gemini CLI has no `/rename` equivalent**, so use the env var or the `set_session_name` tool below.\n- **`set_session_name` tool** β your CLI agent can call it programmatically (works for every host)\n\n### Group them\n\nDrag cards between groups in the dashboard. Groups match by **cwd** or **session name** β stable identifiers that survive CLI restarts. Click `+ New group` to add one; click the name to rename inline; `delete` twice to remove.\n\n### Share a browser across sessions\n\nUnder the hood, one Chromium instance serves all sessions. Session A can open `https://example.com`; session B can call `eval_js` on that same page; session C can screenshot it. Useful for coordinated debugging flows where one agent drives and another inspects.\n\n### Focus a session's terminal\n\nEach session card has a small `β` button on its right side. Click it to bring that session's terminal window to the foreground with the correct tab selected β typing lands straight in the agent's prompt (Claude / Gemini / Codex, whichever the card is). Useful when the dashboard shows something finished and you need to jump to it.\n\n- **macOS:** any session, regardless of terminal. Walks Terminal.app / iTerm2 tabs by tty, with first-class tmux support. First use triggers a one-time automation-permission prompt asking to let `node` control Terminal.app / iTerm2 β click Allow; subsequent clicks work without a prompt.\n- **Windows:** sessions running inside WezTerm only β detected via the `WEZTERM_PANE` env var. Other Windows terminals (Windows Terminal, ConEmu, cmd, pwsh, git-bash) hide the button. Uses `wezterm cli activate-pane` to switch panes and a small PowerShell helper to raise the GUI window.\n- **Linux:** not yet supported β the button is hidden.\n\n---\n\n### Compatibility matrix\n\n| Host | Cards + drag/drop | Tools | Live activity pill | In-transcript rename |\n|---|---|---|---|---|\n| Claude Code | β | β | β | β `/rename` |\n| Gemini CLI | β | β | β | π‘ (`/rename` not built-in, but should work in practice; else, env var or `set_session_name` tool) |\n| Codex CLI | β | β | β Extended mode (Limited shows working/idle only β no tool names) | β `/rename` |\n\n---\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `SESSIONS_DASHBOARD_PORT` | `8787` | Port the daemon binds to on loopback. All sessions must agree. |\n| `SESSIONS_DASHBOARD_AUTOSTART` | unset | Set to `1` to register this session at startup, so it appears in the dashboard before any tool is invoked. The installer doesn't set this by default β opt in if you want eager registration. |\n| `SESSIONS_DASHBOARD_HOST` | auto | `claude`, `gemini`, or `codex`. When unset, detected by probing each host's transcript dir for one matching this cwd. The installer pins this per registration so the probe is bypassed. |\n| `SESSIONS_DASHBOARD_SESSION_NAME` | unset | Sticky display name for this session (cross-host). |\n| `CLAUDE_SESSION_NAME` | unset | Claude-era alias for `SESSIONS_DASHBOARD_SESSION_NAME`. |\n\nSet these in the MCP server's `env` block in your CLI's config file β see [docs/INSTALL.md](docs/INSTALL.md#per-cli-manual-install) for the per-CLI config syntax (Claude / Gemini settings.json, Codex config.toml). `SESSIONS_DASHBOARD_AUTOSTART=1` is recommended β it ensures every session shows up in the dashboard without you having to manually invoke a tool first.\n\n---\n\n## Tools\n\nThe MCP entry point is `mcp__sessions-dashboard__open_dashboard`. The package also exports nine other tools for shared-browser scripting (`open_webview`, `eval_js`, `screenshot`, β¦) β see [docs/TOOLS.md](docs/TOOLS.md) for the full reference.\n\n---\n\n## Troubleshooting\n\n- **`daemon_info` returns the PID** β use `taskkill /F /PID