TMUX

Permite que agentes criem sessões, dividam painéis, executem comandos e capturem saída com TMUX

Documentação

tmux-mcp-rs

tmux-mcp-rs é um servidor Model Context Protocol (MCP) para tmux. Ele permite que clientes MCP criem sessões, moldem janelas e painéis, executem comandos rastreados, inspecionem saídas, gerenciem buffers do tmux e controlem programas interativos de terminal por meio de ferramentas estruturadas, em vez de frágil captura de tela.

Use-o quando um agente precisar de um TTY real, comandos de longa duração, painéis paralelos, estado de terminal retomável ou uma sessão tmux à qual um humano possa se anexar durante a mesma tarefa.

[!WARNING] Este servidor pode permitir que um cliente MCP execute comandos de shell, digite em painéis, leia a saída do terminal, modifique sessões tmux e leia ou grave buffers do tmux. A política de runtime padrão é permissiva. Use sockets tmux isolados e uma política config.toml antes de expô-lo a um cliente em que você não confia totalmente.

O que o servidor oferece

Ferramentas de sessão, janela, painel, cliente e buffer com entradas e saídas estruturadas.
execute-command e get-command-result para comandos de shell com IDs de comando, URIs de recurso, status, saída e rastreamento de código de saída por canal lateral (waitMs opcional; prefira resource subscribe para conclusão).
Recursos de painel, janela, sessão, cliente, servidor e comandos rastreados para verificações leves de estado sem reexecutar ferramentas.
Ferramentas opcionais de entrada bruta para programas interativos, prompts, REPLs e TUIs.
Controles de política de runtime para filtragem de ferramentas, filtragem de comandos, escopo de socket/sessão/painel e grupos de operação amplos.
Flags de recurso em tempo de compilação que removem ferramentas de entrada bruta do binário para builds endurecidos.
Roteamento SSH opcional para que o servidor MCP local possa controlar um servidor tmux remoto.

O caminho MCP costuma ser mais confiável do que uma skill tmux simples, porque cada operação tem uma ferramenta nomeada, parâmetros tipados, IDs estáveis e respostas estruturadas. Os clientes não precisam inferir IDs de painéis a partir de texto capturado nem analisar a saída de comandos para determinar se um comando terminou.

Requisitos

tmux 3.0 ou mais recente em PATH.
Rust 1.70 ou mais recente ao compilar a partir do código-fonte.
Um shell suportado pelo rastreador de comandos: bash, zsh ou fish.

Na inicialização, o servidor executa tmux -V. Ele encerra ao detectar tmux 2.x, pois o tmux 2.x usa formatos de saída e flags de divisão diferentes. Se a versão não puder ser detectada, a inicialização continua e os erros do tmux são relatados pelas chamadas de ferramenta afetadas.

Instalação

Cargo

cargo install tmux-mcp-rs

Homebrew

brew install bnomei/tmux-mcp/tmux-mcp-rs

npm

npx @bnomei/tmux-mcp-rs --version
# or: npm install -g @bnomei/tmux-mcp-rs

O pacote npm é um wrapper fino: na primeira execução, ele baixa o binário correspondente do GitHub Release, verifica o .sha256, o armazena em cache e encaminha o argv.

Docker

docker run --rm ghcr.io/bnomei/tmux-mcp:0.6.0 --version

A imagem é autocontida: inclui Alpine tmux 3.x e o binário Linux musl pré-compilado. As sessões são executadas dentro do contêiner, não no servidor tmux do seu desktop.

Padrão (recomendado para Docker): sandbox de agente isolado. A anexação humana usa docker exec (veja abaixo).
Opcional (somente Linux): monte um socket tmux do host para que o contêiner controle um servidor do lado do host ao qual você pode tmux attach nativamente. O Docker Desktop no macOS/Windows geralmente não consegue alcançar sockets Unix do host dessa forma.
Para anexação conjunta fácil entre humano e agente em um laptop, prefira Homebrew, cargo ou npm no host em vez de Docker.

Cliente MCP stdio (mantenha o stdin anexado):

docker run --rm -i \
  --name tmux-mcp \
  -v "$PWD:/workspace" \
  ghcr.io/bnomei/tmux-mcp:0.6.0

Acompanhe uma sessão criada dentro do contêiner:

docker exec -it tmux-mcp tmux attach -t workspace

Conexão de socket do host Linux (avançado):

# host: start an isolated tmux server
tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace

# container: talk to that socket (image still needs its own tmux client)
docker run --rm -i \
  -v /tmp/tmux-mcp-agent.sock:/tmp/tmux-mcp-agent.sock \
  --user "$(id -u):$(id -g)" \
  ghcr.io/bnomei/tmux-mcp:0.6.0 \
  --socket /tmp/tmux-mcp-agent.sock

# host: attach as usual
tmux -S /tmp/tmux-mcp-agent.sock attach -t workspace

Faça o UID/GID do contêiner corresponder ao proprietário do socket quando houver falha de permissões. Mais detalhes: packaging/README.md.

GitHub Releases

Baixe um arquivo pré-compilado de GitHub Releases, extraia-o e coloque tmux-mcp-rs no seu PATH.

A partir do código-fonte

git clone https://github.com/bnomei/tmux-mcp.git
cd tmux-mcp
cargo build --release

O binário é gravado em target/release/tmux-mcp-rs.

Verifique a instalação

tmux -V
tmux-mcp-rs --version

Saída esperada:

tmux 3.x
tmux-mcp-rs <version>

Início rápido

Adicione o servidor ao seu cliente MCP.

Codex CLI:

codex mcp add tmux -- tmux-mcp-rs

Claude Code:

claude mcp add --transport stdio tmux -- tmux-mcp-rs

Configuração genérica de cliente MCP:

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp-rs"
    }
  }
}

No seu cliente MCP, peça ao agente para criar ou listar sessões tmux.

Uma primeira tarefa típica é:
```
Create a tmux session named workspace, list its windows and panes, then run pwd in the first pane.
```
As respostas das ferramentas devem incluir um ID de sessão, ID de janela, ID de painel e um commandId para o comando rastreado.
Anexe-se à mesma sessão tmux se quiser observar ou participar.
```
tmux attach -t workspace
```

Para trabalho multiagente mais seguro, comece com um socket isolado em vez do servidor tmux padrão:

tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace
tmux -S /tmp/tmux-mcp-agent.sock attach -t workspace

Em seguida, configure o servidor MCP com --socket /tmp/tmux-mcp-agent.sock, TMUX_MCP_SOCKET=/tmp/tmux-mcp-agent.sock ou uma substituição socket por ferramenta.

Configuração do cliente

Use args quando seu cliente MCP aceitar configuração JSON:

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp-rs",
      "args": [
        "--shell-type",
        "zsh",
        "--socket",
        "/tmp/tmux-mcp-agent.sock",
        "--config",
        "/path/to/config.toml"
      ]
    }
  }
}

Para um servidor tmux remoto, adicione --ssh:

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp-rs",
      "args": [
        "--ssh",
        "user@host",
        "--socket",
        "/tmp/tmux-mcp-agent.sock"
      ]
    }
  }
}

Toda ferramenta MCP, exceto socket-for-path, aceita um parâmetro opcional socket. Se uma ferramenta o omitir, o servidor usa o socket padrão do processo.

Referência de configuração

tmux-mcp-rs não carrega automaticamente um arquivo de configuração. Passe um com --config /path/to/config.toml.

Opções de CLI

Opção	Padrão	Descrição
`--shell-type <SHELL>`	`bash`	Shell usado para rastreamento de comandos com reconhecimento de shell. Valores suportados: `bash`, `zsh`, `fish`. Se `[shell].type` existir no arquivo de configuração, o valor da configuração vence.
`--config <PATH>`	unset	Arquivo de configuração TOML a ser lido. TOML inválido, regexes inválidas e ferramentas ou grupos desconhecidos causam falha na inicialização.
`--socket <PATH>`	socket padrão do tmux	Define `TMUX_MCP_SOCKET` para este processo do servidor. Um parâmetro `socket` por ferramenta ainda vence nessa chamada.
`--ssh <CONNECTION>`	unset	Roteia comandos tmux via SSH. Este valor vence sobre `[ssh].remote` e `TMUX_MCP_SSH`.
`--help`	n/a	Exibe a ajuda da CLI.
`--version`	n/a	Exibe a versão do binário.

Variáveis de ambiente

Variável	Descrição
`TMUX_MCP_SOCKET`	Caminho padrão do socket tmux quando nenhuma substituição `socket` por ferramenta é fornecida. Se não definido, o servidor usa o caminho padrão do socket do tmux: `$TMUX_TMPDIR/tmux-$UID/default`, ou `/tmp/tmux-$UID/default` quando `TMUX_TMPDIR` não está definido.
`TMUX_MCP_SSH`	String de conexão SSH usada quando `--ssh` e `[ssh].remote` não estão definidos. A string é analisada com regras de palavras de shell. Aspas desbalanceadas causam falha na inicialização.
`TMUX_MCP_TOOLS`	Substituição por processo para `[security.tools]`. Use `allow:<items>` ou `deny:<items>`. Sem um prefixo, o valor é tratado como uma denylist.
`RUST_LOG`	Habilita a saída de rastreamento por meio de `tracing-subscriber` quando definido. Os logs são gravados no stderr.

Regras de precedência:

Configuração	Precedência
Socket	Parâmetro `socket` por ferramenta, depois `--socket` ou `TMUX_MCP_SOCKET`, depois o caminho padrão do socket do tmux.
SSH	`--ssh`, depois `[ssh].remote`, depois `TMUX_MCP_SSH`, depois sem SSH.
Tipo de shell	`[shell].type`, depois `--shell-type`, depois `bash`.
Filtro de ferramentas	`TMUX_MCP_TOOLS`, depois `[security.tools]`, depois modo de negação sem itens negados.

Exemplo de configuração

[shell]
type = "zsh"

[ssh]
remote = "user@host"

[security]
enabled = true
allow_execute_command = true
allow_raw_mode = true
allow_send_keys = false
allow_kill = true
allow_create = true
allow_split = true
allow_rename = true
allow_move = true
allow_capture = true
allow_list = true
allowed_sockets = ["/tmp/tmux-mcp-agent.sock"]
allowed_sessions = ["workspace"]
allowed_panes = ["%1"]
allowed_buffer_paths = ["/srv/tmux-mcp-buffers"]

[security.command_filter]
mode = "allowlist"
patterns = ["^cargo ", "^git ", "^rg ", "^sed "]

[security.tools]
mode = "deny"
items = ["@raw-input"]

[tracking]
capture_initial_lines = 1000
capture_max_lines = 16000
completed_retention_minutes = 240
completed_max_entries = 1000
tracking_deadline_seconds = 600

[search]
streaming_threshold_bytes = 262144

Opções de segurança

Chave	Tipo	Padrão	Descrição
`security.enabled`	boolean	`true`	Habilita verificações de política. Defina como `false` somente quando quiser ignorar todas as verificações de política.
`security.allow_execute_command`	boolean	`true`	Permite `execute-command` e `get-command-result`.
`security.allow_raw_mode`	boolean	`true`	Permite `execute-command` com `rawMode=true`, que envia o comando sem marcadores de rastreamento.
`security.allow_send_keys`	boolean	`true`	Permite ferramentas de entrada bruta: `send-keys`, `send-hex`, `paste-text` e auxiliares de teclas especiais.
`security.allow_kill`	boolean	`true`	Permite `kill-session`, `kill-window`, `kill-pane` e `detach-client`.
`security.allow_create`	boolean	`true`	Permite `create-session` e `create-window`.
`security.allow_split`	boolean	`true`	Permite `split-pane`.
`security.allow_rename`	boolean	`true`	Permite ferramentas de renomeação de sessão, janela e painel.
`security.allow_move`	boolean	`true`	Permite ferramentas de foco, redimensionamento, zoom, layout, junção, divisão, troca, movimentação e sincronização de painéis.
`security.allow_capture`	boolean	`true`	Permite `capture-pane` e ferramentas de leitura, gravação e busca de buffers do tmux. As operações de arquivo de buffer fazem parte dessa superfície de captura.
`security.allow_list`	boolean	`true`	Permite ferramentas de listagem de sessão, janela, painel, cliente, buffer e sessão atual.
`security.allowed_sockets`	string array ou unset	unset	Quando definido, o socket efetivo para toda solicitação de ferramenta e recurso deve corresponder exatamente a um desses caminhos.
`security.allowed_sessions`	string array ou unset	unset	Quando definido, as operações com escopo de sessão são limitadas a IDs ou nomes exatos de sessão tmux na lista.
`security.allowed_panes`	string array ou unset	unset	Quando definido, as operações diretas de painel são limitadas aos IDs de painel listados.
`security.allowed_buffer_paths`	string array ou unset	unset	Diretórios canônicos permitidos para `save-buffer` e `load-buffer`. Quando não definido, os caminhos devem ser relativos e permanecer sob o diretório `tmux-mcp-buffers/` do diretório temporário local, ou `/tmp/tmux-mcp-buffers/` via SSH. Uma lista vazia nega todos os caminhos de arquivo de buffer.
`security.command_filter.mode`	`off`, `allowlist`, `denylist`	`off`	Modo de filtro de comandos por regex.
`security.command_filter.patterns`	string array	`[]`	Padrões de regex usados pelo filtro de comandos.
`security.tools.mode`	`deny`, `allow`	`deny`	Modo de filtro de superfície de ferramentas em runtime.
`security.tools.items`	string array	`[]`	Nomes exatos de ferramentas ou grupos como `@raw-input`.

security.command_filter verifica cada instrução de shell não vazia quanto a execute-command, send-keys (literal e não literal), paste-text, set-buffer, append-buffer e os bytes decodificados passados para send-hex. Ele divide ;, |, & e quebras de linha sem aspas e, em seguida, verifica recursivamente substituições de comando, substituições de processo, subshells e grupos de chaves. Ele rejeita formas de shell que não consegue analisar com segurança, incluindo aspas ANSI-C $'...' e wrappers de shell -c. Ele não filtra auxiliares de teclas especiais. Para um limite rígido, desative as ferramentas de entrada bruta em runtime ou compile-as fora do binário.

Opções de rastreamento

Chave	Padrão	Descrição
`tracking.capture_initial_lines`	`1000`	Linhas do painel capturadas ao atualizar a saída parcial de um comando em execução.
`tracking.capture_max_lines`	`16000`	Máximo de linhas do painel capturadas ao extrair a saída final entre os marcadores START/DONE visíveis ao humano.
`tracking.capture_backoff_factor`	`2`	Aceito para compatibilidade de configuração. A conclusão por canal lateral não usa mais backoff de captura.
`tracking.completed_retention_minutes`	`240`	Limite de idade para o histórico de comandos concluídos retido em memória.
`tracking.completed_max_entries`	`1000`	Máximo de entradas de comandos concluídos retidas em memória. Defina como `0` para desativar a poda por contagem de entradas e confiar apenas no tempo de retenção.
`tracking.tracking_deadline_seconds`	`600`	Quanto tempo o observador do canal lateral espera por `tmux wait-for` antes de marcar `tracking_error`.

Opções de busca

Chave	Padrão	Descrição
`search.streaming_threshold_bytes`	`262144`	Limiar de tamanho de buffer onde a busca flui por um arquivo temporário em vez de carregar o texto completo do buffer em uma única string para a passagem de busca.

Reforço de segurança

Por padrão, a aplicação de políticas está habilitada, mas permissiva:

Todos os controles amplos allow_* são true.
command_filter.mode é off.
allowed_sockets, allowed_sessions, allowed_panes e allowed_buffer_paths não estão definidos. As operações de arquivo de buffer permanecem restritas ao sandbox padrão do diretório temporário.
[security.tools] está em modo de negação sem itens negados.

Esse padrão é conveniente para experimentação local, mas não é um sandbox.

Use um socket tmux isolado

tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace
tmux-mcp-rs --socket /tmp/tmux-mcp-agent.sock --config config.toml

[security]
allowed_sockets = ["/tmp/tmux-mcp-agent.sock"]

Quando allowed_sockets está definido, chamadas sem um socket explícito ainda resolvem para o socket padrão do processo e devem corresponder à lista de permissões.

Remova a entrada bruta em tempo de execução

[security]
allow_send_keys = false

[security.tools]
mode = "deny"
items = ["@raw-input"]

Use isso quando a entrada do shell deve passar por execute-command para que a filtragem de comandos e o rastreamento de resultados de comandos permaneçam centrais.

Exponha apenas ferramentas de leitura e execução de comandos rastreados

[security.tools]
mode = "allow"
items = ["@read", "execute-command"]

@read inclui get-command-result, ferramentas de listagem, ferramentas de captura, ferramentas de leitura/busca de buffer e socket-for-path.

Substitua a superfície de ferramentas para um processo

TMUX_MCP_TOOLS=send-keys,paste-text tmux-mcp-rs
TMUX_MCP_TOOLS=deny:@raw-input tmux-mcp-rs
TMUX_MCP_TOOLS=allow:@read,execute-command tmux-mcp-rs

Compile sem as ferramentas de entrada bruta

O conjunto de recursos padrão do Cargo inclui interactive e special-keys.

interactive registra send-keys, send-hex e paste-text.
special-keys registra send-cancel, send-eof, send-escape, send-enter, send-tab, send-backspace, send-up, send-down, send-left, send-right, send-page-up, send-page-down, send-home e send-end.

Desative esses recursos para remover as ferramentas do binário:

# Filtered-only build: execute-command is the only shell-input path.
cargo build --release --no-default-features --features rayon,rapidfuzz

# Keep raw keystrokes but remove special-key helpers.
cargo build --release --no-default-features --features rayon,rapidfuzz,interactive

execute-command está sempre registrado e permanece sujeito a security.command_filter.

Referência de ferramentas MCP

A disponibilidade das ferramentas depende dos recursos do Cargo e da política de tempo de execução. Ferramentas negadas em tempo de execução são removidas da lista de ferramentas MCP anunciada e negadas quando chamadas.

Grupos de ferramentas

Grupo	Ferramentas
`@all`	Toda ferramenta conhecida compilada no binário.
`@read`	`socket-for-path`, ferramentas de listar/encontrar, `capture-pane`, ferramentas de leitura/busca de buffer e `get-command-result`.
`@socket`	`socket-for-path`.
`@list`	`list-sessions`, `find-session`, `list-windows`, `list-panes`, `list-clients`, `list-buffers`, `get-current-session`.
`@execute`	`execute-command`, `get-command-result`.
`@capture`	`capture-pane`.
`@buffer-read`	`list-buffers`, `show-buffer`, `search-buffer`, `subsearch-buffer`.
`@buffer-write`	`save-buffer`, `load-buffer`, `delete-buffer`, `set-buffer`, `append-buffer`, `rename-buffer`.
`@create`	`create-session`, `create-window`.
`@split`	`split-pane`.
`@rename`	`rename-session`, `rename-window`, `rename-pane`.
`@move`	`move-window`, `select-window`, `select-pane`, `resize-pane`, `zoom-pane`, `select-layout`, `join-pane`, `break-pane`, `swap-pane`, `set-synchronize-panes`.
`@kill`	`kill-session`, `kill-window`, `kill-pane`, `detach-client`.
`@interactive`	`send-keys`, `send-hex`, `paste-text`.
`@special-keys`	`send-cancel`, `send-eof`, `send-escape`, `send-enter`, `send-tab`, `send-backspace`, `send-up`, `send-down`, `send-left`, `send-right`, `send-page-up`, `send-page-down`, `send-home`, `send-end`.
`@raw-input`	Todas as ferramentas `@interactive` e `@special-keys`.

Ferramentas por tarefa

Tarefa	Ferramentas
Utilitário de socket	`socket-for-path` deriva um caminho determinístico `/tmp/<hash>.sock` a partir de um caminho de projeto.
Gerenciamento de sessão	`list-sessions`, `find-session`, `create-session`, `kill-session`, `get-current-session`, `rename-session`.
Gerenciamento de janela	`list-windows`, `create-window`, `kill-window`, `rename-window`, `move-window`, `select-window`, `select-layout`, `set-synchronize-panes`.
Gerenciamento de painel	`list-panes`, `split-pane`, `kill-pane`, `rename-pane`, `capture-pane`, `select-pane`, `resize-pane`, `zoom-pane`, `join-pane`, `break-pane`, `swap-pane`.
Execução de comando	`execute-command` retorna `commandId` + `resourceUri`; prefira `resources/subscribe` e depois leia em `resources/updated`, ou `get-command-result` com `waitMs`.
Gerenciamento de cliente	`list-clients`, `detach-client`.
Inspeção de buffer	`list-buffers`, `show-buffer`, `search-buffer`, `subsearch-buffer`.
Mutação de buffer	`save-buffer`, `load-buffer`, `delete-buffer`, `set-buffer`, `append-buffer`, `rename-buffer`.
Entrada bruta	`send-keys`, `paste-text`, `send-hex`, `send-cancel`, `send-eof`, `send-escape`, `send-enter`, `send-tab`, `send-backspace`, `send-up`, `send-down`, `send-left`, `send-right`, `send-page-up`, `send-page-down`, `send-home`, `send-end`.

Prefira execute-command com assinatura/leitura de recurso (ou get-command-result + waitMs) para comandos não interativos. Comandos rastreados ficam em fila por painel. Use capture-pane apenas para progresso ao vivo; não trate os marcadores DONE do painel como autoritativos. Use ferramentas de entrada bruta apenas para prompts, REPLs, editores, pagers e TUIs—e não enquanto um comando rastreado estiver em execução nesse painel.

Os snapshots de comandos rastreados usam schemaVersion: 1 e atualmente passam por queued, running, depois completed, failed ou tracking_error. O esquema também reserva cancelled, mas o rastreador atual não o emite. Comandos rastreados normais rejeitam novas linhas embutidas, marcadores de comentário de shell sem aspas (#) e operadores de segundo plano sem aspas (&) porque essas formas podem contornar o epílogo de rastreamento. Defina rawMode=true ou noEnter=true apenas quando você intencionalmente quiser desativar o rastreamento de conclusão por canal lateral; esses registros permanecem running.

show-buffer lê no máximo 65,536 bytes por padrão. search-buffer tem como padrão 40 bytes de contexto, 50 correspondências e 65,536 bytes varridos por buffer; ele retorna deslocamentos de bytes e cursores de retomada quando os resultados são truncados. A busca literal e por regex está sempre disponível. Correspondência difusa e pontuações de similaridade exigem o recurso Cargo rapidfuzz, que está habilitado por padrão.

Referência de recursos MCP

Os recursos de servidor, painel, janela, sessão e cliente refletem o socket padrão do servidor. Os recursos de comandos rastreados mantêm o socket efetivo registrado pelo execute-command de origem, incluindo substituições de socket por ferramenta. Os recursos são enumerados dinamicamente e filtrados pela política de segurança atual.

Apenas os recursos de resultado de comandos rastreados suportam resources/subscribe; leia o recurso após um evento notifications/resources/updated. Outros URIs de recurso fornecem snapshots sob demanda.

URI	Descrição
`tmux://server/info`	JSON com socket padrão e contexto SSH.
`tmux://pane/{paneId}`	Últimas 200 linhas de um painel como texto simples.
`tmux://pane/{paneId}/info`	Metadados do painel como JSON.
`tmux://pane/{paneId}/tail/{lines}`	Últimas N linhas de um painel como texto simples.
`tmux://pane/{paneId}/tail/{lines}/ansi`	Últimas N linhas de um painel com cores ANSI.
`tmux://window/{windowId}/info`	Metadados da janela como JSON.
`tmux://session/{sessionId}/tree`	Snapshot de sessão, janela e painel como JSON.
`tmux://clients`	Clientes tmux como JSON.
`tmux://command/{commandId}/result`	Status e saída de comando rastreado.

Fluxos de trabalho remotos e de socket

SSH remoto

Use --ssh para executar comandos tmux em outra máquina. A autenticação SSH deve ser não interativa, como um agente ou login baseado em chave.

tmux-mcp-rs --ssh "user@host"

Passe opções SSH antes do destino:

tmux-mcp-rs --ssh "-i ~/.ssh/key user@host"

A string de conexão é dividida com regras de palavras de shell. O destino deve ser o último token. O servidor coloca o comando tmux remoto entre aspas antes de enviá-lo ao SSH, e a verificação de versão do tmux se aplica ao tmux remoto quando ele pode ser alcançado.

Remoto com socket isolado

Crie um servidor tmux dedicado no host remoto:

ssh user@host 'tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace'

Inicie o servidor MCP local contra esse socket remoto:

tmux-mcp-rs --ssh "user@host" --socket /tmp/tmux-mcp-agent.sock

Anexe diretamente de um shell quando necessário:

ssh -t user@host 'tmux -S /tmp/tmux-mcp-agent.sock attach -t workspace'

Isolamento de socket

Use --socket ou TMUX_MCP_SOCKET para manter um agente em um servidor tmux:

tmux-mcp-rs --socket /tmp/tmux-mcp-agent.sock

TMUX_MCP_SOCKET=/tmp/tmux-mcp-agent.sock tmux-mcp-rs

Pré-crie a sessão quando quiser um espaço de trabalho visível ao humano antes de o cliente MCP iniciar:

tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace
TMUX_MCP_SOCKET=/tmp/tmux-mcp-agent.sock tmux-mcp-rs

Docker e sockets

A imagem GHCR inclui tmux 3.x e usa por padrão sessões autocontidas dentro do contêiner (docker exec … tmux attach). Somente no Linux, você pode, em vez disso, montar um socket do host para que o servidor MCP do contêiner conduza um servidor tmux do host—veja Instalação → Docker e packaging/README.md. O Docker Desktop no macOS/Windows não é um caminho confiável para socket do host; use uma instalação nativa quando precisar de co-anexação local fácil.

Padrões de fluxo de trabalho do agente

Os testes de integração cobrem estes fluxos de trabalho do tmux:

Padrão	Superfície de ferramentas
Segmentação por ID primeiro	`list-windows`, `list-panes`, `rename-window`.
Layout de tarefa por sessão	`create-session`, `create-window`, `split-pane`, `rename-pane`, ferramentas de listagem.
Contexto de shell com estado	`send-keys`, `capture-pane`.
Painel de saída contínua	`send-keys`, `capture-pane`.
Automação de prompt interativo	`send-keys`, `capture-pane`.
Interrupções interativas	`send-cancel`, `send-eof`, `capture-pane`.
Transmissão de painéis sincronizados	`set-synchronize-panes`, `send-keys`, `capture-pane`.
Transferência e busca de buffer	`list-buffers`, `show-buffer`, `save-buffer`, `delete-buffer`, `search-buffer`, `subsearch-buffer`.
Reorganizações de painel	`split-pane`, `select-layout`, `swap-pane`, `break-pane`, `join-pane`.
Metadados e zoom	Ferramentas de renomear, `zoom-pane`, `resize-pane`, recursos de painel/janela.
Pacote de contexto pronto para auditoria	`execute-command`, `get-command-result`, `capture-pane`.
Orquestração de agente	`create-window`, `split-pane`, `execute-command`, `send-keys`, `capture-pane`.

Para fluxos de trabalho do tmux voltados a agentes, veja:

tmux-buffer-explorer usa buffers do tmux como um espaço de busca externo para textos grandes. É útil quando um agente precisa de busca limitada e fatias de acompanhamento em vez de carregar um buffer inteiro no contexto.

Desenvolvimento

Compile o binário:

cargo build --release

Execute testes unitários que não exigem tmux:

cargo test --lib
cargo test --test cli
cargo test --test search

Execute testes de integração baseados em tmux:

TMUX_MCP_INTEGRATION=1 cargo test --test integration

Os testes de integração criam servidores tmux isolados usando sockets temporários e os limpam em seguida.

Execute as mesmas verificações Rust do CI:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets

As notas de versão e os detalhes de empacotamento de versão estão em CHANGELOG.md e docs/RELEASE.md.

Notas e limitações

O tmux é dono dos buffers de colagem, enquanto este servidor mantém snapshots de comandos rastreados em memória. paste-text, set-buffer, append-buffer e grandes saídas de comandos retidas ainda podem consumir memória do host. A saída rastreada é limitada por linhas pelo capture_max_lines, mas as strings retidas e o comprimento de cada linha não são limitados por bytes.
A busca em buffers transmite buffers grandes por um arquivo temporário após search.streaming_threshold_bytes, mas os buffers do tmux em si não são removidos por tamanho.
As linhas do tmux são analisadas a partir da saída -F delimitada por tabulações. Uma tabulação literal dentro de um título de painel, caminho ou campo semelhante pode deslocar campos posteriores e produzir linhas malformadas ou ignoradas.
paste-text usa marcadores de colagem entre colchetes (bracketed paste). Shells e programas que não suportam bracketed paste podem tratar quebras de linha incorporadas como Enter. No macOS, o /bin/bash 3.2 padrão não suporta o comportamento moderno de bracketed paste; zsh ou um bash mais recente é mais seguro para entrada multilinha que não deve ser enviada linha por linha.
save-buffer grava no sistema de arquivos do servidor tmux, e load-buffer lê dele. Ambos são regidos por allow_capture, [security.tools] e security.allowed_buffer_paths. Com a política padrão habilitada, os chamadores usam caminhos relativos dentro do sandbox tmux-mcp-buffers/ do diretório temporário local ou /tmp/tmux-mcp-buffers/ via SSH; travessia de diretórios pai e escapes canônicos ou por symlink são rejeitados.
Os resultados de comandos são vinculados ao socket. get-command-result deve usar o mesmo socket efetivo da chamada original execute-command.
A conclusão de comandos rastreados usa um buffer de saída privado do tmux + sinal wait-for, não o scrollback de painel forjável. As linhas opcionais START/DONE são apenas para humanos/depuração.
send-keys/paste-text interativos durante uma execução rastreada no mesmo painel é indefinido; aguarde o comando terminar ou use outro painel.
O comportamento SSH de ponta a ponta é verificado manualmente porque o CI não fornece um host remoto.

Âncoras de código-fonte

Análise de CLI e comportamento de inicialização: src/main.rs
Ferramentas MCP, recursos e instruções do servidor: src/server.rs
Política de segurança e grupos de ferramentas: src/security.rs
Rastreamento de comandos: src/commands.rs
Comportamento do socket tmux, SSH e wrapper de processos: src/tmux.rs
Tipos de dados públicos: src/types.rs
Testes de CLI: tests/cli.rs
Fluxos de trabalho de integração: tests/integration.rs
Testes de busca em buffers: tests/search.rs

Licença

Licença MIT. Consulte LICENSE.