convez.ai
MCP ServerDevOps & InfraestruturaAvançado
rjprins

agmux — Painel Web para Agentes CLI

rjprins/agmux

Painel web local para gerenciar agentes CLI com streaming PTY e automação

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que fornece uma interface web local para gerenciar sessões de terminal de agentes de código (Claude Code, Codex, etc.) com streaming PTY em tempo real via WebSocket, persistência via tmux e detecção de prontidão. Permite controlar múltiplos agentes CLI, organizar por worktrees, restaurar sessões inativas e automatizar fluxos com sistema de triggers customizáveis.

Instalação

$npx convez-ai rjprins/agmux

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
0
Saúde
100%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerenciar múltiplas sessões Claude Code ou Codex simultaneamente
  • Monitorar e automatizar fluxos de trabalho de agentes de código
  • Restaurar e retomar sessões de agentes interrompidas ou inativas

Veredito

Ferramenta robusta e especializada para desenvolvedores que precisam orquestrar múltiplos agentes CLI em paralelo. Arquitetura sólida com WebSocket, tmux e triggers, mas exige Node.js v22+, tmux e compilação de dependências nativas — indicado para equipes técnicas, não para usuários casuais.

README

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

agmux

Local web UI for managing agent terminal sessions. Streams PTY output to the browser over WebSockets, with customizable triggers and Claude/Codex readiness callbacks backed by tmux pane inference fallback.

Built for managing Claude Code, Codex, and other CLI-based coding agents — but works with any terminal program.

Features

  • Live terminal dashboard — stream tmux-backed PTYs over WebSockets, switch sessions quickly, rename/kill sessions, and keep shells alive across server restarts.
  • Agent launch workflows — start shells, Codex, Claude, or custom CLI agents in an existing worktree, a new worktree, or the current project, with saved flags and launch preferences.
  • Worktree-aware sidebar — group projects, sort sessions by worktree, pin or archive projects, and keep same-worktree sessions visually tied together by their left rail color.
  • Readiness detection — mark Claude/Codex sessions ready through callbacks, with tmux pane inference as a fallback for prompts, permission requests, and idle shells.
  • Inactive session discovery and restore — discover recent Claude, Codex, and Pi sessions from provider logs, preview conversations, and restore them into the same cwd, an existing worktree, or a new worktree.
  • PR review context — poll Azure DevOps PR state for active sessions, surface unresolved/new comment markers, and expand review threads from the PR bar.
  • Task context — configure project task providers, list/update Beads tasks, and attach task references to launched or running sessions.
  • MCP control surface — expose local tools for listing PTYs, sending input, taking snapshots, launching agents, attaching tmux sessions, renaming/killing PTYs, and restoring agent sessions.
  • Trigger system — hot-reload custom triggers from triggers/index.js, match terminal output, and orchestrate sessions through trigger hooks.
  • Desktop and mobile UI — use the full desktop terminal view or a mobile-first agent view with quick prompts, scrollback snapshots, and touch-friendly controls.
  • Local-first safety controls — optional token auth for /api/* and /ws, loopback binding by default, theme/settings persistence, input history, and tmux inspection helpers.

Prerequisites

  • Node.js v22+
  • npm
  • tmux (for persistent sessions — the default backend)
  • C++ toolchain (build-essential on Debian/Ubuntu) for native addons

On Ubuntu/Debian:

sudo apt install tmux build-essential

See docs/dependencies.md for the full list.

Quick Start

git clone https://github.com/rjprins/agmux.git
cd agmux
npm install
npm run dev

This starts the app with auto-rebuild and auto-reload.

  • App: http://127.0.0.1:4821

If you get "address already in use", pick a different port:

PORT=4823 npm run dev

Start app only (no file watching):

npm run app

Triggers

Edit triggers/index.js. The server watches the triggers/ folder and hot-reloads on change.

An example trigger is included that highlights the PTY in the UI when a proceed (y)? prompt is detected.

Trigger onMatch(ctx) handlers can also orchestrate other sessions via ctx.hooks:

  • ctx.hooks.writeTo(ptyId, data) — write input to another running PTY
  • ctx.hooks.listPtys() — inspect current PTY summaries
  • ctx.hooks.spawnShell({ cwd?, name? }) — spawn a new tmux-backed shell PTY

Agent API

Use the current UI API surface directly for agents:

Claude / Codex readiness

Claude and Codex callbacks are the preferred readiness signal. If those callbacks are not configured or do not fire, agmux falls back to the original tmux pane-based readiness inference.

A PTY becomes ready immediately when:

  • Claude Code fires a Notification hook such as idle_prompt or permission_prompt
  • Codex runs its notify callback after a turn completes

Without an explicit callback, agmux still infers readiness from visible tmux pane state:

  • changing pane content keeps the PTY busy
  • a stable prompt long enough marks the PTY ready
  • visible permission prompts also count as ready

Every agmux-created shell exports these variables:

  • AGMUX_PTY_ID
  • AGMUX_TMUX_SESSION
  • AGMUX_API_BASE
  • AGMUX_READY_HELPER
  • AGMUX_TOKEN when token auth is enabled

Example Claude hooks:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$AGMUX_READY_HELPER\" claude idle_prompt"
          }
        ]
      },
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$AGMUX_READY_HELPER\" claude permission_prompt"
          }
        ]
      }
    ]
  }
}

Example Codex config:

notify = ["node", "/absolute/path/to/agmux/scripts/agent-ready.mjs", "codex", "turn_complete"]

Using the exported helper is preferred inside agmux-created shells because it already knows the current PTY and auth token.

Configuration

Environment variables:

VariableDefaultDescription
HOST127.0.0.1Server bind address
PORT4821Server port
DB_PATHdata/agmux.dbSQLite database path
TRIGGERS_PATHtriggers/index.jsTrigger definitions file
AGMUX_TOKEN_ENABLEDfalseEnable auth token enforcement for /api/* and /ws
AGMUX_TOKEN(generated if enabled and unset)Auth token value when AGMUX_TOKEN_ENABLED=1
AGMUX_LOG_LEVELwarnFastify log level (fatal,error,warn,info,debug,trace)
AGMUX_SHELL$SHELL or bashShell for PTY sessions
AGMUX_SHELL_BACKENDtmuxPTY backend: tmux or pty
AGMUX_NO_OPENfalseSkip auto-opening browser
AGMUX_ALLOW_NON_LOOPBACKfalseAllow binding to non-localhost addresses
AGMUX_ALLOWED_ORIGINSAdditional WebSocket origins (comma-separated)
AGMUX_INACTIVE_MAX_AGE_HOURS24Hide non-running sessions older than this
AGMUX_LOG_SESSION_DISCOVERY1Enable/disable inactive discovery from JSONL logs
AGMUX_LOG_SESSION_SCAN_MAX500Max JSONL files scanned per discovery refresh
AGMUX_LOG_SESSION_CACHE_MS5000Cache lifetime for discovered log sessions
CLAUDE_CONFIG_DIR~/.claudeRoot used for Claude log discovery
CODEX_HOME~/.codexRoot used for Codex log discovery
PI_HOME~/.piRoot used for Pi log discovery

Optional auth token

By default, agmux does not require an auth token.

To enable auth explicitly, set AGMUX_TOKEN_ENABLED=1:

AGMUX_TOKEN_ENABLED=1 npm run app

With AGMUX_TOKEN_ENABLED=1:

  • if AGMUX_TOKEN is set, that value is used
  • if AGMUX_TOKEN is unset, agmux generates a random token at startup

When token auth is enabled:

  • all /api/* endpoints require the token (x-agmux-token header, Authorization: Bearer, or ?token=...)
  • WebSocket /ws requires the token
  • browser auto-open includes ?token=... automatically
  • startup logs print a clear token/auth status message

See docs/auth-token.md for details and examples.

Testing

# Unit tests
npm test

# E2E tests (Playwright)
npm run e2e

# E2E with browser visible
npm run e2e:headed

By default, E2E tests use Playwright's managed Chromium. Set PLAYWRIGHT_CHROMIUM_PATH to use a system browser instead.

To install Playwright's browser:

npx playwright install chromium

Notes

  • Plain PTYs (created via /api/ptys) are not persistent — if the Node server stops, those processes stop too.
  • The default "New PTY" shell is tmux-backed, so it survives server restarts.
  • Click an inactive session row to attempt resume/re-attach.
  • WebSocket output is batched (~16ms flush interval) for performance.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

See SECURITY.md for reporting vulnerabilities. agmux runs terminal sessions — please report security issues responsibly.

License

MIT

Ver o original no GitHub

Bom para

Relacionados