convez.ai
AgenteAutomaçãoAvançado
adelost

agentmux - Orquestração Multi-Agent para Claude Code

adelost/agentmux

Orquestre múltiplos agentes Claude Code em tmux com Discord ChatOps

Ver no GitHub
InicialPluginScore · de 0 a 100

Ferramenta local para coordenar múltiplos agentes Claude Code e Codex em painéis tmux, com interface ChatOps no Discord e CLI amux. Oferece orquestração de sessões, isolamento de histórico, tratamento de mídia e controles operacionais para fluxos de desenvolvimento assistido por IA.

Instalação

$npx convez-ai adelost/agentmux

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 dia
Versão
agentmux-link-v1.2.24
Issues abertas
1
Contribuidores
1

Casos de uso

  • Executar várias sessões Claude Code em paralelo para delegação de tarefas
  • Coordenar fluxos de trabalho de desenvolvimento com interface Discord
  • Gerenciar históricos isolados de sessões com recuperação de falhas
  • Compartilhar arquivos, imagens e mensagens de voz entre agentes

Veredito

Solução robusta para quem precisa orquestar múltiplos agentes Claude em paralelo em ambiente local. Requer infraestrutura (tmux, Node.js 20+, Discord) e conhecimento técnico, mas oferece controle fino sobre sessões distribuídas com safeguards operacionais.

README

A tradução para o português deste README ainda está na fila.

agentmux

agentmux is local developer tooling for coordinating Claude Code and Codex agents across tmux panes. It adds a Discord-based ChatOps interface, a terminal CLI, session isolation, structured logs, media handling, and operational safeguards for long-running AI-assisted development workflows.

Discord / amux CLI
        -> agentmux bridge
        -> tmux panes
        -> Claude Code / Codex
        -> structured logs, status, files, and replies

agentmux runs on your machine. It does not host agents for you; it connects your local projects, tmux sessions, and coding-agent CLIs into one controllable workspace.

Why agentmux

  • Run multiple Claude Code and Codex sessions side by side.
  • Keep pane histories isolated so resume/continue does not cross wires.
  • Delegate work between agents through the amux CLI.
  • Inspect status, logs, timelines, and recent completed work from one place.
  • Send and receive files, screenshots, PDFs, voice messages, and TTS replies.
  • Recover stuck sessions with explicit operational commands.
  • Protect long-running sessions with loop detection, reminders, and auto-compact support.

Core Concepts

ConceptPurpose
AgentA named project workspace from agentmux.yaml
PaneOne Claude Code or Codex session inside a tmux window
BridgeThe Node.js process that connects Discord, tmux, and logs
amuxCLI for sending prompts, reading logs, checking status, and coordinating panes
.agents/Generated per-pane working directories and instruction files

Pane 0 runs in the project root. Pane 1 and above run in .agents/N/, giving each coding agent its own session history while still letting Claude Code and Codex discover generated project instructions.

Features

Multi-agent orchestration

  • Route different Discord channels to different projects and panes.
  • Run several Claude Code and Codex sessions per project.
  • Delegate tasks from one agent to another with amux <agent> -p <pane> "...".
  • Fan out tests, audits, screenshots, or implementation work in parallel.

Reliable session management

  • Structured jsonl history for Claude and Codex output extraction.
  • Retry loop with delivery verification.
  • Resume hints for panes that restart without prior context.
  • Model-aware context tracking.
  • Recovery commands for stuck panes and blocking prompts.

Media and operator workflows

  • Voice message transcription.
  • Text-to-speech replies.
  • File and image transfer in both directions.
  • Agent-generated image attachments through [image: /absolute/path.png].
  • Optional Voice PWA endpoint for trusted local or tailnet clients.

Requirements

  • Linux, macOS, or WSL
  • Node.js 20+
  • tmux
  • At least one supported coding-agent CLI:
    • Claude Code
    • Codex CLI
  • A Discord bot token if you want the Discord bridge

Quick Start

git clone https://github.com/adelost/agentmux
cd agentmux
bash bin/setup.sh

The setup script checks prerequisites, installs npm dependencies, and creates starter config files.

Create or edit agentmux.yaml:

guild: "YOUR_DISCORD_SERVER_ID"
category: "Agent Cave"

agents:
  api:
    dir: ~/projects/api
    panes: 2
    codex: 1
    shells: 2

  frontend:
    dir: ~/projects/frontend
    panes: 2

Start the bridge:

npm run dev

In Discord, run:

/sync

This creates or updates the project channels from agentmux.yaml.

Discord Setup

  1. Create a bot in the Discord Developer Portal.
  2. Enable Message Content Intent for the bot.
  3. Invite the bot to your server with permissions to send messages, read history, attach files, and manage channels.
  4. Put the token in .env:
DISCORD_TOKEN=your-token-here
  1. Put your Discord server ID in agentmux.yaml.
  2. Start agentmux and run /sync.

Everyday Commands

Discord commands:

CommandDescription
/syncCreate or update Discord channels from config
/statusShow current agent, pane, and context usage
/peekShow the last response from the target pane
/rawShow raw tmux pane output
/escSend Escape to the target pane
/dismissDismiss a blocking prompt where supported
/use <agent>[.pane]Temporarily retarget the channel
/reloadReload config
/restartRestart the bridge process

Terminal commands:

amux ps
amux api -p 1 "run the test suite and summarize failures"
amux wait api -p 1
amux log api -p 1
amux log api -p 1 --tmux
amux timeline --since 30min
amux done --since 2h
amux asks --open
amux esc api -p 1

Personal todos with daily 08:00 push:

amux todo                      # list active
amux todo add "buy SSD"        # to Idag / snart
amux todo add --parked "..."   # later
amux todo done 5               # by id (or substring)
amux todo rm 5
amux todo-remind --dry         # preview push
bin/install-todo-cron.sh       # enable daily reminder

Backed by ~/.openclaw/workspace/memory/tasks.md. Full docs in docs/todo.md.

ax is installed as a shorter alias for amux.

Agent-to-Agent Delegation

Agents can use amux from their own terminal, so one pane can coordinate others:

amux api -p 1 "run backend tests"
amux frontend -p 1 "audit the dashboard layout"
amux wait api -p 1
amux wait frontend -p 1
amux log api -p 1
amux log frontend -p 1

Generated .agents/CLAUDE.md and .agents/AGENTS.md files teach Claude Code and Codex how to use these commands from inside project panes.

Configuration

Common .env variables:

VariableDefaultDescription
DISCORD_TOKENrequiredDiscord bot token
AGENTMUX_YAML./agentmux.yamlConfig file path
TMUX_SOCKET/tmp/agentmux.socktmux socket used by agentmux
TIMEOUT_S600Max wait for a pane response
TTS_VOICEsv-SE-MattiasNeuraledge-tts voice
AGENTMUX_RECORD0Save request/response recordings when set to 1

See agentmux.yaml.example for a fuller project config example.

Documentation

  • Reliability: Loop Guard, Drift Guard, Auto-Compact, and recovery commands.
  • CLI Reference: amux commands, log modes, timelines, and orchestrator commands.

Troubleshooting

If a pane does not respond:

amux log <agent> -p <pane> --tmux
amux esc <agent> -p <pane>
amux wait <agent> -p <pane>

From Discord, use /raw, /esc, /dismiss, or //new for the same recovery path.

If Discord channels are missing or stale, run /sync again after checking agentmux.yaml.

Tests

npm test

License

MIT

Ver o original no GitHub

Bom para

Relacionados