convez.ai
AgenteProdutividadeIntermediário
wolzey

Agent Factory

wolzey/agent-factory

Arcade retrô para visualizar agentes Claude em tempo real

Ver no GitHub
InicialPluginScore · de 0 a 100

Visualização em pixel art 2D de sessões de agentes Claude Code/Codex em tempo real. Transforme as operações do seu time em um arcade retrô interativo, onde cada agente ativo é representado como um avatar animado trabalhando em cabines de arcade com efeitos neon.

Instalação

$npx convez-ai wolzey/agent-factory

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
3
Acompanhando
0
Saúde
28%
Último commit
há 1 mês
Versão
v0.22.3
Issues abertas
1
Contribuidores
2

Casos de uso

  • Monitorar múltiplas sessões de agentes em equipe simultaneamente
  • Visualizar fluxo de trabalho e paralelismo entre agents
  • Depuração colaborativa com visibilidade compartilhada de sessões

Veredito

Solução criativa e funcional para visualização em tempo real de agentes distribuídos. Implementação sólida em TypeScript/Node com WebSocket, mas o escopo é bastante específico (Claude Code/Codex) e requer setup de servidor compartilhado para full value.

README

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

Agent Factory

A 2D pixel art visualization of Claude Code/Codex agent sessions. Watch your team's agents work in a retro arcade game room in real time.

Retro arcade themed visualization Hook events

What it does

  • Each active Claude Code or Codex session appears as an animated pixel art avatar
  • Working agents stand at arcade cabinets with neon glow effects
  • Idle agents hang out in the lounge area
  • Subagents orbit their parent with a purple tint
  • Hover over any avatar to see session details (username, project, current tool, task description)
  • Team members connect to a shared server to see everyone's agents at once
  • Log in from the browser to send emotes and chat via a terminal-style command prompt

Quick Install (Team Members)

If someone on your team is already running the server, just install the hooks:

curl -fsSL https://raw.githubusercontent.com/wolzey/agent-factory/main/install-cli.sh | bash

This downloads a small binary and runs an interactive wizard that:

  1. Asks for your display name
  2. Asks for the server URL (they'll give you this)
  3. Lets you pick an avatar color and style
  4. Installs the hooks into your Claude Code and/or Codex settings

Requirements: curl, Claude Code and/or Codex installed

For non-interactive installs (CI, scripting):

agent-factory install --non-interactive --server-url https://your-server.example.com --username alice

Running the Server

Prerequisites

  • Node.js 18+
  • pnpm

Setup

git clone https://github.com/wolzey/agent-factory.git
cd agent-factory
pnpm install
pnpm dev

This starts:

  • Server on http://localhost:4242 (HTTP + WebSocket)
  • Client on http://localhost:5173 (Vite dev server)

Open http://localhost:5173 in your browser to see the arcade.

Exposing to your team

Use ngrok, Tailscale, or any tunnel to expose port 4242:

# ngrok
ngrok http 4242

# Then tell your team to install with:
# curl -fsSL https://raw.githubusercontent.com/wolzey/agent-factory/main/install-cli.sh | bash
# and enter the ngrok URL when prompted

Production

pnpm build
pnpm start  # serves on port 4242 (both API and static client)

Set PORT and HOST environment variables to customize. Set ENVIRONMENT to choose a background: arcade, farm, office, or mining.

How It Works

Claude/Codex Hooks  ──curl POST──>  Fastify Server  ──WebSocket──>  Browser (Phaser 3)
(ephemeral bash)                   (port 4242)                     (2D pixel art arcade)
  1. Hooks fire on Claude Code/Codex events (session start/end, tool use, subagent spawn/stop)
  2. The hook script reads ~/.config/agent-factory/config.json for your identity
  3. It curls the event data to the server (fire-and-forget, never blocks Claude)
  4. The server updates its in-memory state and broadcasts via WebSocket
  5. The browser renders the Phaser 3 scene with animated avatars

Hook Events Tracked

EventWhat happens in the arcade
SessionStartAvatar spawns at the entrance, walks to lounge
PreToolUseAvatar walks to an arcade cabinet, starts working
PostToolUseNeon sparkle effect
SubagentStartMini-avatar warps in near parent
SubagentStopMini-avatar dissolves
StopAvatar walks back to lounge
SessionEndAvatar walks to exit, fades out

Tool Activity Mapping

ToolsAvatar activity
Read, Glob, GrepReading (magnifier icon)
Write, EditWriting (pencil icon)
BashRunning (terminal icon)
WebSearch, WebFetchSearching (globe icon)
AgentChatting (chat icon)
EnterPlanModePlanning (brain icon)

Browser Commands

You can send emotes and chat directly from the browser. First, get your auth token:

agent-factory token

This prints a token like d29semV5.a1b2c3d4.... Copy it, then:

  1. Open the Agent Factory page in your browser
  2. Click Login (top-left corner)
  3. Paste your token and click Login

Once logged in, a terminal-style command bar appears at the bottom. Available commands:

CommandDescription
/emote <name>Trigger an emote (dance, jump, guitar, gun, laugh, wave, sleep, explode, dizzy, flex, rage, fart)
/chat <message>Send a chat message visible to all viewers
/helpShow available commands
/logoutLog out of the browser session
bare textSent as a chat message (no / prefix needed)

Your login persists across page refreshes via localStorage and automatically re-authenticates on reconnect.

Note: The agent-factory token command must be run on the machine running the server (tokens are generated via a localhost-only endpoint). Share tokens with team members who need browser access.

CLI Commands

CommandDescription
agent-factory installInteractive setup wizard (hooks, config, avatar)
agent-factory uninstallRemove hooks and config
agent-factory updateUpdate CLI to latest release
agent-factory tokenDisplay your auth token for browser login
agent-factory emote <name>Trigger an emote on your agent
agent-factory chat <message>Send a chat message
agent-factory avatarCustomize your avatar

Configuration

Your config lives at ~/.config/agent-factory/config.json:

{
  "username": "ethan",
  "serverUrl": "http://localhost:4242",
  "token": "ZXRoYW4.a1b2c3d4e5f6...",
  "avatar": {
    "spriteIndex": 0,
    "color": "#4a90d9",
    "hat": null,
    "trail": null
  }
}
FieldDescription
usernameDisplay name shown on your avatar's nametag
serverUrlAgent Factory server URL (localhost or shared)
tokenAuth token for browser login (auto-generated)
avatar.spriteIndexCharacter style (0-7)
avatar.colorHex color for your avatar tint
avatar.hatHat accessory (future feature)
avatar.trailTrail effect (future feature)

Uninstall

agent-factory uninstall

This removes all Agent Factory hook entries from ~/.claude/settings.json and ~/.codex/hooks.json (surgically, preserving your other hooks) and deletes ~/.config/agent-factory/.

Architecture

agent-factory/
├── server/           # Fastify HTTP + WebSocket server
│   ├── index.ts      # Entrypoint (port 4242)
│   ├── state.ts      # In-memory session state machine
│   ├── auth.ts       # HMAC-SHA256 token auth
│   ├── routes/       # POST /api/hooks, GET /api/health, GET /api/auth/token
│   ├── ws/           # WebSocket broadcast manager (per-socket auth)
│   └── cleanup.ts    # Stale session reaper (5 min timeout)
├── client/           # Phaser 3 browser app
│   ├── scenes/       # BootScene, FactoryScene, UIScene
│   ├── entities/     # AgentSprite, SubagentSprite, Machine
│   ├── systems/      # AgentManager, LayoutManager
│   ├── auth/         # AuthManager (localStorage token persistence)
│   ├── ui/           # ChatOverlay, LoginOverlay, CommandInput
│   └── network/      # WebSocket client with auto-reconnect
├── shared/           # Types and constants shared between server/client
├── cli/              # Go CLI binary
│   ├── cmd/          # Cobra commands (install, uninstall, token, emote, chat, avatar, update)
│   ├── internal/     # Config, hooks, wizard, UI helpers
│   └── main.go       # Entry point
├── hooks/            # Claude/Codex hook scripts (legacy)
└── install-cli.sh    # Bootstrap script (downloads CLI binary)

API

REST Endpoints

EndpointDescription
POST /api/hooksReceives hook events from Claude Code/Codex
POST /api/emoteTrigger an emote ({ username, emote })
POST /api/chatSend a chat message ({ username, message })
POST /api/contextUpdate agent task description ({ username, summary })
GET /api/auth/token?username=XGenerate auth token (localhost-only)
GET /api/healthServer status ({ status, agents, clients, uptime })
GET /api/stateAll active agent sessions
GET /api/configServer config (title, environment, graphicDeath)

WebSocket (ws://host:4242/ws)

Server -> Client: full_state, agent_update, agent_remove, effect, chat_message, auth_result

Client -> Server: request_state, auth (token login), emote, chat

License

MIT

Ver o original no GitHub

Bom para

Relacionados