Skip to content

Installation and Updates

ChrAlpha edited this page Nov 12, 2026 · 4 revisions
🇬🇧English | 🇨🇳中文

Installation and Updates

Requirements

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.

Install

Let your agent do it

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.

By hand

  1. Add the plugin to tmux.conf and press prefix + I:

    set -g @plugin 'ChrAlpha/tmux-agent-experience'

    On load the plugin downloads the released tmag binary 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 inside bin/ 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.

  2. 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, and tmag-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: their tmag is 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.

  3. Start new agent sessions in tmux panes. In Codex, approve tmag's hooks with /hooks, and run /title once to turn on thread-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-experience
run-shell ~/.tmux/plugins/tmux-agent-experience/tmag.tmux

Update

prefix + 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.

Uninstall

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.

Clone this wiki locally