tmux-agent MVP

This minimal MVP provides three main pieces:

• agent-sidebar.tmux
• tmux-agent

Build

make

This produces:

./bin/tmux-agent

The existing build script still works:

./scripts/build.sh

Install

make install

By default this installs:

/usr/local/bin/tmux-agent
/usr/local/share/tmux-agent/agent-sidebar.tmux

You can override the install prefix if needed:

make install PREFIX="$HOME/.local"

Load in tmux

Add this to ~/.tmux.conf:

source-file /usr/local/share/tmux-agent/agent-sidebar.tmux

Then reload your tmux config:

tmux source-file ~/.tmux.conf

Default key binding:

• prefix + A: open or close the right sidebar
• prefix + N: switch between the current normal window and its corresponding agent window; if the target side does not exist, create it in the same directory and register the agent window in the sidebar

The tmux plugin defaults @agent-sidebar-bin to tmux-agent, so make sure the installed binary is in your PATH, or override it in ~/.tmux.conf:

set -g @agent-sidebar-bin "/absolute/path/to/bin/tmux-agent"

The plugin also installs tmux hooks so that:

• opening the sidebar immediately focuses it
• moving focus away from the sidebar automatically closes it

This behavior is implemented with tmux focus-events and the pane-focus-out hook, which calls tmux-agent close --pane-id #{hook_pane}.

The plugin also prepends a single aggregated agent slot to status-right:

• A:0: no agent windows
• A:3: three active agent windows
• A:2?: at least one agent is waiting for input
• A:1!: at least one agent is in error

If needed, you can override the dedicated agent session name:

set -g @agent-sidebar-agent-session-name "__agent__"

For the dedicated __agent__ session, tmux-agent also sets:

set -t __agent__ detach-on-destroy off

so when that session is destroyed, tmux switches the client back to the most recently active remaining session. This only applies to the agent session, not globally to every tmux session.

Manually write test state

Run this inside a tmux pane:

export TMUX_AGENT_RUNTIME_KEY="codex-$(date +%s)-$$"
./bin/tmux-agent prepare \
  --source codex \
  --runtime-key "$TMUX_AGENT_RUNTIME_KEY" \
  --title "new codex window"

./bin/tmux-agent start \
  --source codex \
  --runtime-key "$TMUX_AGENT_RUNTIME_KEY" \
  --title "demo codex task" \
  --status running

Then run:

./bin/tmux-agent update \
  --runtime-key "$TMUX_AGENT_RUNTIME_KEY" \
  --status waiting_input \
  --title "waiting for review"

prepare can be called as soon as a new tmux window is created so the pane is immediately classified as an agent pane in the sidebar. start then promotes the same runtime to running when the real agent process begins.

The sidebar will show the state in the Agents section.

Hook examples

Example scripts live in:

• examples/hooks/codex/
• examples/hooks/claude/

These scripts call the shared tmux-agent binary and write state into tmux pane options and runtime JSON.

Notes

This is still a minimal MVP:

• It supports a right sidebar
• It shows both agent items and normal sessions
• It supports Codex and Claude as sources
• Hook config files still need to be wired into your local CLI setup

Not implemented yet:

• Rich detail views
• Fine-grained hook payload parsing
• TPM auto-install support