Tenex

Terminal multiplexer for AI coding agents

Tenex lets you run multiple AI coding agents in parallel, each in an isolated git worktree with its own branch. Spawn agent swarms for research, planning, or code review—then synthesize their findings back together.

Features

• Parallel agents — Run multiple AI coding agents simultaneously (Claude CLI by default; also supports Codex or a custom command)
• Git isolation — Each root agent works in its own worktree and branch; child agents share the root's worktree
• Optional Docker runtime — New root agents can launch inside Docker; child agents and terminals inherit the root runtime. This is mainly intended for Tenex development rather than general-purpose day-to-day use.
• Swarm workflows — Spawn planning or review swarms with one keystroke
• Synthesis — Aggregate outputs from descendant agents into a parent (captures last ~5000 lines from each, writes to markdown, then sends to parent)
• Live preview — Watch agent output in real-time with ANSI color support; auto-follows bottom unless you scroll
• Diff view — See uncommitted changes (staged + unstaged + untracked) vs HEAD in the selected agent's worktree
• Commits view — See commits in the selected agent's branch (relative to base) in a dedicated tab
• Git operations — Push, rebase, merge, rename branches, and open PRs from the TUI
• Command palette — Run slash commands like /agents and /help
• Persistent state — Agents survive restarts; auto-reconnects to existing worktrees on startup
• Auto-update — Checks crates.io for updates on startup and prompts to install

Requirements

• Built-in PTY backend — No external multiplexer required
• git — Required for worktree isolation
• gh — GitHub CLI, required for opening pull requests (Ctrl+o)
• An agent CLI — claude (default) or codex (or configure a custom command)
• Platform support — Linux and macOS native; Windows via WSL2
• Rust 1.91+ — For building from source
• cargo — Required for auto-update functionality

Linux Installation

# Install from crates.io
curl https://sh.rustup.rs -sSf | sh
cargo install tenex --locked

# Or build from source
git clone https://github.com/Mockapapella/tenex
cd tenex
cargo install --path .

Quick Start

# Navigate to any git repository
cd your-project

# Launch Tenex
tenex

# Press 'a' to create your first agent
# Press '?' for help

Keybindings

Agents

Terminals

Git

Navigation

Configuration

The default agent command is claude --allow-dangerously-skip-permissions. Press / to open the command palette, run /agents, then choose which agent type to configure (default/planner/review).

Data Storage

On startup, Tenex migrates legacy data from ~/.local/share/tenex/ to ~/.tenex/.

Environment Variables

If TENEX_STATE_PATH is relative, it resolves from the current working directory.

CLI Commands

tenex              # Launch the TUI
tenex reset        # Clear all agents and state
tenex reset --force # Force reset without confirmation
tenex --help       # Show help
tenex --version    # Show version

Workflows

Spawn Swarm

Press S to create a new root agent with N child agents. You'll be prompted for: 1. Number of children 2. Task prompt (sent to all children)

Planning Swarm

Press P for a planning-focused swarm. Children receive a planning preamble prompt and are titled "Planner N". Use s to synthesize their findings when done.

Review Swarm

Press R to spawn code reviewers: 1. Pick number of reviewers 2. Select base branch (searchable list with ↑/↓ navigation)

Reviewers get a strict review preamble with the chosen base branch. They're titled "Reviewer N".

Synthesis

Press s to synthesize. This: 1. Captures the last ~5000 lines from each descendant's terminal buffer 2. Writes combined output to .tenex/<uuid>.md in the parent's worktree 3. Kills and removes all descendants 4. Sends the parent a command to read the synthesized file

Broadcasting

Press B to send a message to all leaf agents (agents with no children). Terminals are excluded. Useful for giving the same instructions to all workers in a swarm.

Merge Conflicts

When rebase or merge encounters conflicts, Tenex opens a terminal window titled "Merge Conflict" or "Rebase Conflict" in the worktree, runs git status, and leaves resolution to you.

Keyboard Compatibility

On first launch, Tenex checks if your terminal supports the Kitty keyboard protocol (to distinguish Ctrl+m from Enter). If not supported, you'll be prompted to remap the merge key to Ctrl+n. This choice is saved to settings.json.

Troubleshooting

Copying text / mouse selection

Tenex captures the mouse so it can support wheel scrolling and pane-isolated text selection (similar to tmux panes).

To copy output from the Terminal Output pane: - Click + drag to select lines - Release to copy to your clipboard - (Uses OSC 52; if your terminal blocks it, disable Tenex mouse support and use native selection)

TENEX_DISABLE_MOUSE=1 tenex  # disable Tenex mouse support (use your terminal's native selection)

Agents Disappear Immediately

If a newly-created agent flashes into existence and vanishes a few seconds later, it usually means the underlying agent process exited during startup (Tenex then prunes the agent because its mux session is gone).

• Enable logs with DEBUG=3 tenex and inspect the log at /tmp/tenex.log.
• Tenex stores the mux socket name in ~/.tenex/state.json so sessions can survive rebuilds/upgrades.
• After upgrading Tenex, you may still have an older tenex muxd running (old behavior persists until the daemon is restarted). Tenex will prompt you to restart it on launch.
• To force a fresh mux daemon, set an explicit socket: TENEX_MUX_SOCKET=/tmp/tenex-mux.sock tenex.

License

Apache-2.0