Repository navigation
Installation and Updates
tmux 3.2 or newer on Linux or macOS (amd64 or arm64),
TPM, curl, and any of Claude Code,
Codex, Pi or oh-my-pi.
Paste this into your coding agent, running in a tmux pane:
Read https://raw.githubusercontent.com/ChrAlpha/tmux-agent-experience/main/SKILL.md and follow it to install or update tmag for the AI tool I am using.
The agent asks before touching your tmux configuration, installs the plugin, connects the agent it runs in, and verifies the result. SKILL.md is the same procedure, readable by people. Use the same prompt to update.
-
Add the plugin to tmux.conf and press
prefix + I:set -g @plugin 'ChrAlpha/tmux-agent-experience'
On load the plugin downloads the released
tmagbinary for its version, checks its SHA-256, and keeps it in its own directory,$TMUX_PLUGIN_MANAGER_PATH/tmux-agent-experience/bin/(usually~/.tmux/plugins/tmux-agent-experience/bin/). Version checks run in that background worker. Each of its two curl downloads has a 10-second connection limit and a 25-second total transfer limit, with no retries. These are network limits; local tools, filesystems and an existing executable have no whole-attempt deadline. Installation stages insidebin/and atomically replaces the executable only after checksum and version checks: installers that run at once each publish the same release, and one that was interrupted leaves nothing that blocks the next. Missing curl is reported; installation never builds from source. -
Press
prefix + M-a. A popup shows the commands that connect the agents you have through their own plugin managers, runs them once you confirm, and checks the result. Each agent gets two plugins:tmag, whose hooks report its state, andtmag-peers, a skill that teaches it to work with the other agents through tmag (see Agents acting on agents). Pi and oh-my-pi have no hooks: theirtmagis an extension that reports instead. They install both as packages from the plugin's own directory (pi install,omp plugin install), so the packages always match the binary and update with the plugin. -
Start new agent sessions in tmux panes. In Codex, approve tmag's hooks with
/hooks, and run/titleonce to turn onthread-id(see Sessions and panes).
Without TPM, clone the repository and run its entry point from tmux.conf:
git clone https://github.com/ChrAlpha/tmux-agent-experience ~/.tmux/plugins/tmux-agent-experiencerun-shell ~/.tmux/plugins/tmux-agent-experience/tmag.tmuxprefix + U updates the plugin; it fetches the matching binary on the next
load. Then prefix + M-a brings the agent plugins to the same version. Codex
holds an approval of hooks to the plugin version it was given for, so after
each update it asks again: approve tmag's hooks with /hooks in a new Codex
session. Pi's and oh-my-pi's packages update with the plugin; new sessions
load them.
tmag uninstall prints the exact removal steps. Remove Pi's and oh-my-pi's
packages before the plugin, which they are installed from. To purge state, run
tmag uninstall --purge while the binary is still installed. See
Footprint for what is removed.