convez.ai
AgenteDevOps & InfraestruturaAvançado
narmaku

Agent Town

narmaku/agent-town

Monitor multi-agente IA com dashboard Web e suporte SSH/LAN

Ver no GitHub
InicialPluginScore · de 0 a 100

Dashboard leve para monitorar e controlar sessões de agentes IA de codificação (Claude Code, OpenCode, Gemini CLI) distribuídas em múquinas da rede local. Suporta navegação por teclado, rastreamento de tokens, visualização de diffs Git e terminal integrado com notificações em tempo real.

Instalação

$npx convez-ai narmaku/agent-town

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
42%
Último commit
há 1 dia
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Monitorar múltiplas sessões de agentes IA em máquinas diferentes
  • Acompanhar uso de tokens e status de agentes em tempo real
  • Navegar diffs Git e controlar sessões zellij/tmux remotas
  • Gerenciar projetos paralelos com agentes Claude Code, OpenCode e Gemini CLI

Veredito

Ferramenta especializada e bem-arquitetada para quem trabalha com múltiplos agentes IA de codificação em rede local. Implementação sólida (TypeScript, WebSocket, SSH tunnels) ideal para workflows colaborativos ou desenvolvimento distribuído, mas com curva de aprendizado moderada.

README

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

Agent Town

A lightweight dashboard to monitor and connect to AI coding agent sessions across machines on your home network. Supports Claude Code, OpenCode, and Gemini CLI via a provider abstraction, with more agents easily added.

Features

  • Multi-agent support: Claude Code, OpenCode, and Gemini CLI (extensible via provider plugins)
  • Explorer and Cards layout modes: switch between compact list and card-based views
  • Configurable keyboard navigation: navigate sessions with j/k, Enter to expand, f for fullscreen, t for terminal, s to send, / to search, ? for help (all shortcuts customizable)
  • Activity feed: cross-session status change notifications with click-to-navigate
  • Git diff viewer: view uncommitted changes per session with file navigation and syntax-highlighted diffs
  • Browser notifications and sound alerts: configurable alerts for session status changes (awaiting input, errors, etc.)
  • Token usage tracking: input/output token counts displayed per session
  • SSH/remote nodes: multi-machine support via SSH tunnels with automatic deployment
  • Full-width cards and true fullscreen session view: distraction-free session monitoring
  • Real-time session monitoring via WebSocket
  • Status detection: working, awaiting_input, action_required, idle, done, error (display names: Working, Awaiting Input, Action Required, Idle, Done, Error — see SessionStatus type in shared/src/index.ts for all values)
  • Multi-machine support over LAN (no VPN needed)
  • Session renaming from the dashboard
  • Terminal relay: attach to zellij/tmux sessions from the browser
  • Launch and resume agent sessions from the dashboard
  • Supports both zellij and tmux

Architecture

Browser (dashboard)
  |
Server (:4680) --- receives heartbeats, serves dashboard, proxies terminals
  |
Agent (per machine) --- discovers sessions via providers, reports status, relays terminals
  |
zellij/tmux sessions --- where AI coding agents (Claude Code, OpenCode, Gemini CLI) run

Quick Start (local dev)

cd ~/development/agent-town
./dev.sh

Open http://localhost:4680

Best Practice: One Terminal Session Per Agent

For the best experience with Agent Town, run each AI coding agent in its own named terminal session. This makes it easy to attach to any agent directly from the dashboard.

With zellij (recommended: minimal layout)

For the cleanest web terminal experience, create a minimal zellij layout without tab bar or status bar:

# Create the minimal layout (one-time setup)
mkdir -p ~/.config/zellij/layouts
cat > ~/.config/zellij/layouts/agent.kdl << 'EOF'
layout {
    pane borderless=true
}
EOF

Then create sessions using this layout:

# Create a named session for each project with minimal UI
zellij -s rubric-kit --layout agent
cd ~/development/rubric-kit && claude

# In another terminal
zellij -s evaluation-data --layout agent
cd ~/development/evaluation-data && claude

# And another
zellij -s deploy --layout agent
cd ~/development/lscore && claude

With tmux

# Create named sessions
tmux new-session -d -s rubric-kit -c ~/development/rubric-kit
tmux send-keys -t rubric-kit "claude" Enter

tmux new-session -d -s evaluation-data -c ~/development/evaluation-data
tmux send-keys -t evaluation-data "claude" Enter

tmux new-session -d -s deploy -c ~/development/lscore
tmux send-keys -t deploy "claude" Enter

Why one session per agent?

  • Clean attach: Agent Town can attach to any session directly from the browser
  • No navigation: You land right where Claude Code is running, not in a tab maze
  • Session names: Give meaningful names that show up in the dashboard
  • Isolation: Each agent has its own terminal environment

Avoid: multiple agents in one session

Mixing multiple Claude Code agents in tabs/panes of a single session means you have to navigate to find the right one after attaching. Agent Town can still monitor all sessions, but the terminal attach won't know which tab to focus.

Running Agent Town

Option 1: Dev script (everything on one machine)

./dev.sh

Starts both the server and agent, builds the dashboard, opens on port 4680.

Option 2: Multi-machine setup

On your Proxmox server (or any central machine):

# Start the server
bun run server/src/index.ts

On each machine with Claude Code sessions:

# Point the agent at the server
AGENT_TOWN_SERVER=http://<server-ip>:4680 bun run agent/src/index.ts

Option 3: Run agent-town outside any multiplexer

For terminal relay to work reliably, the agent process should run outside of the multiplexer sessions it will attach to. Options:

# Run as a background process
nohup ./dev.sh > agent-town.log 2>&1 &

# Or run in its own dedicated tmux/zellij session
tmux new-session -d -s agent-town -c ~/development/agent-town './dev.sh'

Environment Variables

VariableDefaultDescription
AGENT_TOWN_PORT4680Server port
AGENT_TOWN_SERVERhttp://localhost:4680Server URL (for agent)
AGENT_TOWN_INTERVAL5000Heartbeat interval in ms
AGENT_TOWN_TERMINAL_PORT4681Terminal WebSocket port (agent)
AGENT_TOWN_MACHINE_IDauto (hostname hash)Stable machine identifier

Dashboard Features

  • Click a card to expand and see full session details
  • Double-click the slug to rename a session
  • Open Terminal button attaches to the multiplexer session from the browser
  • If multiple terminal sessions exist, a picker appears
  • ESC ESC (double press) closes the terminal overlay

Project Structure

agent-town/
  agent/        # Runs on each machine, discovers sessions via provider plugins
    providers/  # Agent type plugins (claude-code, opencode, gemini-cli)
  server/       # Central hub, receives heartbeats, serves dashboard
  dashboard/    # React SPA with real-time status cards
  shared/       # TypeScript types and logger shared across packages

Tests

bun test
Ver o original no GitHub

Bom para

Relacionados