tomplex

Periscope — Git skill for Claude Code

Git community

Live browser dashboard over tmux sessions — every window becomes a card, modal opens a live xterm.js terminal, parses Claude Code pane status (branch / PR / CI / spinner / recap).

How to install Periscope

This entry records only its repository, not the path inside it, so there is no exact command to give. Open tomplex/periscope and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Periscope does

Live browser dashboard over tmux sessions — every window becomes a card, modal opens a live xterm.js terminal, parses Claude Code pane status (branch / PR / CI / spinner / recap).

Alternatives in Git

Create Worktree + Spawn Agent — git worktree add ../feat-custom-templates -b feat/custom-templates origin/main cd ../feat-custom-templates && 211 ★
Recall — by zippoxer - Full-text search your Claude Code sessions 158 ★
Adversarial Review — humanizer, update_config), custom status bar, MCP integration, and a self-improvement loop that remembers co 125 ★

README

periscope

A live dashboard over your tmux sessions. Every window becomes a card; click into a card to open a full live terminal (xterm.js + tmux `pipe-pane` over WebSocket), send keystrokes, focus the window in tmux, or rename it. Identifies Claude Code and Codex panes alongside ordinary shells, combines their agent state with branch/PR/CI metadata, and surfaces work that is running or ready for attention.

Built for the "I have 30 tmux windows across 5 sessions with coding agents running, and I want a single pane of glass" workflow.

Requirements

tmux (any reasonably modern version)
`uv` for running the single-file script
Node 20+ + npm — the frontend is a Vite-built bundle (static/dist/)
A modern browser (uses WebSockets)
Codex CLI 0.146.0 for the initial, macOS-tested Codex integration
Optional: ANTHROPIC_API_KEY for the ✨ auto-rename feature

Run

npm install && npm run build   # one-time / whenever static/src/ changes
uv run server.py

Open . Polls every 3s; the modal opens a live WebSocket bridge to the selected pane.

For the always-on / launchd-managed setup and the prod/dev port split, see [CLAUDE.md → Development workflow](./CLAUDE.md#development-workflow-prod--dev-split) and `bin/periscope`.

Updating

bin/periscope update

Pulls, regenerates the launchd plist, re-registers the agent hooks, restarts, and waits until `/api/healthz` reports the SHA it just pulled. When the dashboard is running as the launchd service it also nags: the header shows an `↑ N behind` pill once the checkout falls behind, and clicking it runs the same sequence in place.

Use this rather than `git pull` + `bin/periscope restart` — the plist and the hook registration are *generated* by `bin/periscope`, so a plain pull carries neither, and `restart` reuses the already-loaded plist. It aborts without touching the running server if the tree is dirty, the branch has diverged, or i