projmux

npm install -g projmux
projmux shell

Why

Six tmux windows. Each one is running Claude Code or Codex on a different repo. Three are idle. One is waiting on a permission prompt. One crashed an hour ago and you have no idea which.

projmux ingests Claude Code and Codex hook events directly, shows live per-pane state in the tmux status bar, and lets one keystroke take you to the pane that actually needs you. It also remembers each agent's resume id, so after a reboot every pane comes back as the same conversation — not a fresh one.

Requirements

• Node.js and npm, for the main install path.
• tmux 3.4 or newer.

Run projmux doctor after installing to check the local runtime.

Install

The npm package shown above installs a small Node.js shim plus the matching projmux binary for Linux and macOS on x64 or arm64. npm is the primary distribution path for normal users.

Verify with projmux version. Then projmux doctor checks the local runtime (tmux 3.4+ and hook integration health).

Manual Go, source checkout, GitHub Release, and packaging details live in Install.

Quick Start

Open the isolated projmux tmux app:

projmux shell

Inside the app:

• Alt-1 opens the project sidebar.
• Alt-2 opens the notification list.
• Alt-3 opens the existing-session picker.
• Alt-4 opens the AI split picker.
• Alt-5 opens settings.

Those five launch keys are the guaranteed zero-config defaults. Add more aliases in Settings > Keybindings or ~/.config/projmux/keymap.toml. If a key does not fire, run projmux setup outside tmux, then use projmux init [terminal] --apply for supported terminal delivery fallbacks.

Day-To-Day Use

• Pick a project directory and projmux creates or reuses its tmux session.
• Pin important projects so they stay easy to reach.
• Preview windows, panes, git branch, Kubernetes context, and AI pane state before switching.
• Use Settings > Project Picker to add roots and workdirs without editing env vars.
• Use Settings > About > Update or projmux update apply to upgrade.

For detailed configuration, including PROJMUX_PROJDIR, managed roots, notifications, and usage tracking, see Configuration. For update behavior by installer type, see Upgrading.

More Docs

• Install
• Configuration
• Terminal Keybindings
• AI Agent Shortcuts
• CLI Reference
• Statusbar
• Hooks
• Usage tracking
• Agent Workflow
• README Hero GIF Recording

Development

make build
make fmt
make fix
make test

See Testing, Architecture, and Repo Layout for contributor details.

License

MIT. See LICENSE.