# tmux Wiki — Control Mode (GitHub + DeepWiki mirror)

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | shell-multiplexer-auto-attach |
| Document type | Source Dossier |
| Tier | 1 |
| Source title | Control Mode |
| Source URL | https://github.com/tmux/tmux/wiki/Control-Mode |
| Source publisher / author | tmux project wiki |
| Source type | vendor docs |
| Source date (published) | Unknown — not stated |
| Date researched | 2026-10-09 |
| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
| Research method | web search synthesis |
| Confidence | Medium |
| Status | Active |

## Summary

The tmux project's own wiki page on control mode, describing it as a way for a client to talk to tmux using normal tmux commands over plain text (built originally for iTerm2's tmux integration) plus `%`-prefixed control-only notifications. A near-identical mirror of the same material exists at deepwiki.com/tmux/tmux/7.1-control-mode.

## Key findings

- Control mode deliberately reuses the normal tmux command set rather than inventing a separate scripting API — a client only needs to learn the notification framing on top of commands it may already know.
- Originally built for a GUI client (iTerm2) to render tmux panes natively, which is why it emphasizes structured notifications over raw terminal bytes.

## Pros / strengths

- Being the project's own wiki (not a third party's reverse-engineering), this is a materially more trustworthy reference than most blog posts on the topic.

## Cons / limitations / caveats

- A wiki page, not versioned documentation — it may drift from a specific tmux release's actual behavior; cross-check against the installed version's man page.

## Relevance to tai

The authoritative reference to build a tai control-mode client parser against — command reuse plus structured notifications is exactly the "accept commands + emit events" shape the proposal asks for.

## Changelog

| Date | Change |
|---|---|
| 2026-10-09 | Initial dossier created. |