@zerodawn/tmux-sidebar

Shared right-pane tmux sidebar that stacks TASKS (via td view) and AGENTS (via pi-ping render) in one pane, refreshing every 2s.

Install

npm install -g @zerodawn/tmux-sidebar

Provides two binaries on PATH:

• tmux-sidebar — render loop (TASKS + AGENTS), what you run inside the pane
• tmux-sidebar-toggle — open/close the sidebar on the current tmux window

Usage

Keybind

Add to your tmux config (zerodawn ships this in local/shell/tmux/pi.conf):

bind-key S run-shell 'tmux-sidebar-toggle'

prefix + S toggles the sidebar. The new pane is tagged with title pi-sidebar, which is how the toggle finds it again.

Layout

┌──────────────────────┐
│ TASKS                │
│   …td view…          │
│ ─────────────        │
│ AGENTS               │
│   …pi-ping render…   │
└──────────────────────┘

Pane is split right at 25% width, user-resizable. Survives tmux reload via tmux-resurrect.

Behaviour

• Best-effort widgets. A missing td or pi-ping binary shows a dim (… not installed) line; the other widget keeps rendering. A widget exiting non-zero shows (<cmd> exited non-zero); the loop continues.
• Per-window filter. td view auto-reads /tmp/td/window-filters/<window-id>, so the sidebar shows the filter of the window it lives in. No extra wiring.
• Clean exit. SIGINT/SIGTERM exit immediately so closing the pane is silent.

Configuration

Environment variables read on launch:

| Variable | Default | Purpose | | ---------------------- | -------------- | ----------------------------------------------------- | | TMUX_SIDEBAR_REFRESH | 2 (seconds) | Refresh interval for the render loop | | TMUX_SIDEBAR_WIDTH | 25 | Pane width percentage (used by tmux-sidebar-toggle) | | TMUX_SIDEBAR_CMD | tmux-sidebar | Command launched in the new pane (used by toggle) |

Disable

Remove the bind-key S line from your tmux config and reload (tmux source-file ~/.tmux.conf). Uninstall the package with npm uninstall -g @zerodawn/tmux-sidebar.

Development

npm install
npm run smoke

The smoke test exercises renderFrame + toggleSidebar with fake runners — no tmux, td, or pi-ping required.

Related

• Plan: .pi/docs/local/tmux-sidebar/plans/mvp.md
• Companion: @zerodawn/td (TASKS widget), @zerodawn/pi-ping (AGENTS widget)