convez.ai
AgenteAutomaçãoAvançado
lout33

AgentMux

lout33/agentmux

Supervisão e coordenação de agentes IA em tmux com SQLite

Ver no GitHub
InicialPluginScore · de 0 a 100

Plano de controle local para agentes de IA em terminal, usando tmux + SQLite como camada de supervisão. Coordena múltiplos agentes (Claude Code, OpenCode, Codex, shell) em padrão manager/worker, permitindo rastrear estado, enviar prompts e gerenciar projetos multi-agente de um único ponto.

Instalação

$npx convez-ai lout33/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
3
Forks
0
Acompanhando
1
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Coordenar múltiplos agentes IA em tarefas de desenvolvimento
  • Manter agentes rodando localmente com histórico e monitoramento
  • Padrão manager/worker para projetos autônomos de exploração

Veredito

Ferramenta robusta para quem precisa orquestrar múltiplos agentes IA em ambiente local. Bem pensada para padrões complexos (manager/worker), mas requer familiaridade com tmux e terminal.

README

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

agentmux

Local control plane for terminal AI agents — tmux + SQLite supervision for Claude Code, OpenCode, Codex, and shell workers

Keep runtimes alive, supervise workers, manage projects — all from one terminal.

agentmux CLI in action

Why

tmux keeps processes alive. But it doesn't tell you what is running, why, or whether it needs attention.

agentmux layers supervision on top of tmux so you can:

  • Name agents, not sessions — give each worker a durable identity
  • Track state — know which agents are active, idle, finished, or failed
  • Send prompts — direct commands to any agent without switching terminals
  • Group by project — see all workers for a repo in one view
  • Watch everything — live dashboard for all running agents

Core model:

  • tmux is the runtime substrate
  • agentmux is the supervision layer
  • one agent = one durable worker identity
  • one runtime = one tmux-backed terminal session for that agent

Real-world pattern: manager + workers

The most powerful way to use agentmux is with a manager agent that spawns and coordinates worker agents across different AI CLIs.

hermes (manager, shell harness)
├── researcher (worker, shell harness)
├── coder (worker, claude harness)
├── reviewer (worker, opencode harness)
└── ops (worker, codex harness)

The manager (in this case called "hermes") runs in a shell harness and delegates work to specialized workers. Each worker uses whatever CLI fits the task — Claude Code for coding, OpenCode for research, Codex for ops, or plain shell for anything else.

# Set up a project with a manager
./agentmux project-sync myproj --workdir /path/to/myproj --harness shell

# Spawn workers with different harnesses
./agentmux worker myproj researcher --harness shell --prompt "research the codebase"
./agentmux worker myproj coder --harness claude
./agentmux worker myproj reviewer --harness opencode

# Watch the whole project from one view
./agentmux watch --project myproj

# Or open the web dashboard
./agentmux web --open

The manager can use the agentmux skill to send prompts to workers, check their state, and coordinate — all from one terminal.

Autonomous explorer projects

An "autonomous explorer" project gives an agent an open-ended goal and lets it self-direct. The manager monitors progress, unblocks when the agent needs human action, and updates the project tracker.

Pattern:

  1. Create the project with a manager shell
  2. Add workers for each autonomous agent
  3. Send the agent its contract as the initial prompt
  4. Monitor via agentmux logs — intervene only when stuck or needing human steps
  5. Kill and delete workers when the project is paused or killed
# Create project manager
./agentmux project-sync my-project --workdir /path/to/project --harness shell

# Add autonomous explorer workers
./agentmux worker my-project explorer-1 --workdir /path/to/repo1 --harness opencode
./agentmux worker my-project explorer-2 --workdir /path/to/repo2 --harness codex

# Send initial mission
./agentmux send explorer-1 "Read AGENTS.md. Start working toward the goal. Ask the human when you need external steps."

# Monitor
./agentmux watch --project my-project
./agentmux logs explorer-1

Requirements

  • python3
  • tmux

Quick start

# Install globally
./agentmux install

# Create an agent
./agentmux new --harness shell --agent demo --prompt "echo hello"

# See what's running
./agentmux ls

# Open the web dashboard
./agentmux web --open

Install the OpenCode skill so any agent can use agentmux:

./agentmux install-skill

Three surfaces

SurfaceWhat it does
CLICreate, supervise, and control agents from the terminal
SkillOpenCode integration so agents know how to use agentmux
Web UIBrowser dashboard for project boards and terminal supervision

Commands

Create and import

./agentmux new --harness shell --agent demo
./agentmux new --harness shell --agent demo --prompt "echo hello"
./agentmux new --harness opencode --agent demo
./agentmux new --harness opencode --agent demo --session ses_abc123
./agentmux new --harness custom --agent demo --cmd python3 --arg -m --arg http.server
./agentmux discover                                    # find untracked tmux sessions
./agentmux import --agent imported --tmux-session ses --harness shell

Inspect

./agentmux ls                                          # list all agents
./agentmux ls --project myproj                         # list agents in a project
./agentmux show demo                                   # agent details
./agentmux logs demo                                   # recent output
./agentmux events --session demo                       # event stream

Control

./agentmux send demo "pwd"                              # send a command
./agentmux send demo "continue" --no-enter              # type without pressing enter
./agentmux attach demo                                  # attach to terminal
./agentmux stop demo                                    # stop the runtime
./agentmux kill demo                                    # kill the agent
./agentmux resume demo                                  # restart a stopped agent
./agentmux resume demo --prompt "continue"              # resume with a command
./agentmux state demo finished                          # set agent state manually
./agentmux delete demo                                  # remove agent record

Projects

./agentmux project-sync myproj --workdir /path/to/myproj --harness shell
./agentmux worker myproj researcher --workdir /path/to/myproj --harness shell
./agentmux worker myproj reviewer --harness shell --prompt "inspect and report"
./agentmux watch --project myproj                       # live view of all project agents
./agentmux console --project myproj                     # interactive console

Web UI

./agentmux web                                          # start the dashboard
./agentmux web --open                                   # start and open browser
./agentmux web --host 127.0.0.1 --port 8421            # custom host/port

Recommended flow:

  1. Run agentmux web --open
  2. Import or open a project
  3. Start the project general agent with the default shell harness
  4. Open worker terminals or send prompts from the project panel
  5. Use the side panel for logs, events, stop, kill, resume, and state updates

Harnesses

HarnessUse for
shellDefault. General-purpose terminal agents
claudeClaude Code sessions
codexOpenAI Codex sessions
piPi AI sessions
opencodeOpenCode sessions
customAny command — pass --cmd and --arg

For opencode sessions, agentmux injects a default model:

  • default: ollama-cloud/glm-5.1
  • override per session: --model provider/model
  • override globally: export AGENTMUX_OPENCODE_MODEL=provider/model

The opencode harness supports --session to resume an existing OpenCode session:

./agentmux new --harness opencode --agent foo --session ses_abc123

This passes -s ses_abc123 to the opencode binary.

Install

CLI

./agentmux install                              # installs to ~/.local/bin
./agentmux install --bin-dir /usr/local/bin      # custom location

Add to your shell profile if needed:

export PATH="$HOME/.local/bin:$PATH"

Skill

./agentmux install-skill                         # global OpenCode skill
./agentmux install-skill --target-dir ~/.agents/skills/agentmux
./agentmux install-skill --force

Restart OpenCode after updating the skill.

Environment variables

AGENTMUX_HOME=/custom/path                       # custom state directory
AGENTMUX_OPENCODE_MODEL=provider/model           # default model for opencode
AGENTMUX_INSTALL_DIR=/usr/local/bin              # custom install directory

State

Runtime state is auto-detected heuristically.

Agent state is manual in v1:

StateMeaning
activeCurrently working
idleWaiting for input
finishedTask complete
failedSomething went wrong
archivedNo longer needed

Local state lives in .agentmux/agentmux.db.

License

MIT


Keywords: ai agent supervisor, tmux agent manager, multi-agent orchestration, terminal agent control plane, claude code manager, opencode manager, codex manager, agentmux, ai agent cluster, terminal ai workers, multi-ai workflow, agent process manager

Ver o original no GitHub

Bom para

Relacionados