convez.ai
AgenteDevOps & InfraestruturaIntermediário
orbenozio

Agentville

orbenozio/claude-code-agentville

Visualize agentes Claude Code como uma vila viva com ciclos dia/noite

Ver no GitHub
InicialPluginScore · de 0 a 100

Visualizador em tempo real que transforma agentes Claude Code em uma vila interativa, mostrando cada agente como um personagem com papéis específicos (construtor, revisor, arquiteto, pesquisador) trabalhando ao redor de uma praça central. Oferece visibilidade visual instantânea sobre atividades paralelas de múltiplos agentes sem interferir nas conversas.

Instalação

$npx convez-ai orbenozio/claude-code-agentville

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
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v0.1.18
Issues abertas
0
Contribuidores
2

Casos de uso

  • Monitorar atividades de múltiplos agentes em paralelo durante sessões Claude Code
  • Compreender fluxos de trabalho complexos com sub-agentes de forma visual e intuitiva
  • Depurar e entender o estado e progresso de agentes sem logs textuais

Veredito

Ferramenta criativa e leve que resolve um problema real de visibilidade em fluxos multi-agente. Abordagem passiva e segura (read-only, sem network) a torna confiável para uso produtivo, embora ainda em desenvolvimento ativo.

README

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

Agentville 🏘️

A live, top-down town view of what your Claude Code agents are doing - right now.

Every agent becomes a little villager. The main session is the mayor in the town hall; each sub-agent is a character around the central square whose role (🏗️ builder · 🔍 reviewer · 📐 architect · 📚 researcher) shows in what they carry. Watch them work, finish (✅), and head home to sleep and dream 💭 - with day/night cycles and live weather over the village.

TypeScript Electron Pixi.js VS Code Extension License: MIT Status Read-only


[!NOTE] Agentville is a passive, read-only observer. It watches Claude Code's local session files to visualize agent activity - it never modifies your conversations, interferes with Claude Code, or sends anything over the network (other than an optional, keyless weather lookup for your chosen city).

📖 Table of Contents

🏘️ What is Agentville?

When you run Claude Code, the main session often spawns sub-agents (via the Task tool) that work in parallel - researching, drafting, reviewing, building. It can be hard to see, at a glance, how many agents are running, what each one is doing, and when they start or finish.

Agentville turns that invisible swarm into a tiny, living town. Each agent is a character living around a central square. When an agent is idle it rests at home; when it goes to work it walks into the square carrying a role-specific prop and shows a thought bubble with its current task. The goal is visual at-a-glance visibility into a Claude Code conversation - without heavy graphics and without any official integration.

Conceptually it's a sibling of Claude Code Nonstop - both are external tools that observe and/or augment Claude Code.

✨ Features

  • 🧑‍🌾 A character per agent - placed around the central square; the main session is the mayor in the town hall.
  • 🛠️ Roles from context - each villager's prop is derived from the agent type + task: 🏗️ builder (a growing structure + hammer) · 🔍 reviewer (magnifying glass) · 📐 architect (notebook + pencil) · 📚 researcher (book) · 🏛️ mayor (scroll).
  • 💬 Task speech bubbles - the agent's description floats above it while it works.
  • 🪧 Village tabs - signposts hop between the other Claude conversations of the same project (each its own "village"), colour-coded, with an optional manual name.
  • 🌅 Day/night cycle - the sky reflects your local time: dawn / day / dusk / night, with a sun arc, moon, and stars; a global tint sets the whole village's mood.
  • 🌦️ Live weather - real weather for a city you choose (keyless, via Open-Meteo): rain / snow / fog / clouds / storm - or pick a mode manually.
  • 🐑 Cute life - farm animals, birds, a flowing river with jumping fish, fruit trees, and street lamps that light up in the evening.
  • 💤 Sleep & dreams - idle agents go home, breathe, and occasionally pop a dream bubble.
  • 🖥️ Runs two ways - as a standalone Electron app or inside a VS Code tab via the bundled extension (with a 🌍 button injected into the Claude Code panel).

🚦 Agent States

Agentville derives and renders the full agent lifecycle. States come from two channels that merge together (see How It Works):

StateIconMeaningSource
idle🏠Resting at home - no recent activityJSONL (time threshold) / hooks (idle_prompt, certain)
working🏭Actively working, with a task bubbleJSONL (open tool uses) + hooks (SubagentStart)
awaitingApproval⏳Waiting for the user to approve a permissionhooks only (Notification:permission_prompt / PermissionRequest)
done✅Sub-agent finished and went homeJSONL (status: completed) / hooks (SubagentStop)
error⚠️Hit an API errorJSONL (isApiErrorMessage) / hooks (StopFailure)
rateLimited😴Waiting out a rate limithooks (StopFailure.error_type)

🔍 How It Works

Claude Code records each conversation as JSONL files under ~/.claude/projects/<encoded-path>/*.jsonl, including calls to the Task tool that spawn sub-agents. Agentville tails those files and derives a real-time feed of agent state - no official API required.

There are two data channels that merge into a single source of truth:

  1. 📄 JSONL channel (always available). Incremental, byte-exact tailing of the session files → parse → normalize → reduce into agent states. This gives the task description for the speech bubble (which the hooks channel does not carry) and works with zero setup.

  2. 🪝 Hooks channel (optional, opt-in). Claude Code's official hooks (SubagentStart / SubagentStop / Notification / PermissionRequest / StopFailure) write events to a file that Agentville reads. This turns several core states from "fragile probabilistic guesses from JSONL" into certain events - most notably ⏳ awaiting-approval and the "silence ≠ idle" problem.

When hooks aren't installed, Agentville falls back gracefully to JSONL-only mode (with reduced certainty on a couple of edge states). The design treats the two channels as a core merge - the hook provides certain id / type / lifecycle / timing, while JSONL provides the task text.

🏗️ Architecture

flowchart LR
    subgraph CC["Claude Code"]
        J["~/.claude/projects/*.jsonl"]
        H["hooks → events.jsonl"]
    end

    subgraph CORE["src/core (pure logic, no Electron/Pixi)"]
        TR["TailReader<br/>(byte-exact incremental tail)"]
        N["normalize<br/>(raw → NormalizedRecord)"]
        R["Reducer<br/>(records → AgentState[])"]
    end

    subgraph MAIN["src/main (Electron main)"]
        SM["SessionMonitor<br/>(watch + merge channels)"]
        IPC["IPC (throttled diffs)"]
    end

    subgraph REND["src/renderer (Pixi.js)"]
        UI["Town view<br/>(a character per agent)"]
    end

    J --> TR
    H --> SM
    TR --> N --> R --> SM
    SM --> IPC --> UI

The core (src/core) is pure, framework-free TypeScript - tail, parse, normalize, reduce - fully unit-tested and validated end-to-end against real sessions during a Phase 0 spike. The main process watches files and merges the two channels; the renderer draws the town with Pixi.js and updates from throttled diffs over IPC.

The core was hardened by a spike that caught and fixed 3 real bugs (false error/rate-limit matches from conversation text, idle↔working flicker from backlog timestamps, and agent-creation diffs being swallowed). See SPIKE-FINDINGS.md.

🚀 Getting Started

Prerequisites

  • Node.js ≥ 20
  • Claude Code installed and used at least once (so ~/.claude/projects/… exists)

Option A - Standalone Electron app

git clone https://github.com/orbenozio/claude-code-agentville.git
cd claude-code-agentville
npm install

# build + launch the town
npm start

Other useful scripts:

npm run spike            # run the core feed live against your real sessions (console)
npm run spike:replay -- <file.jsonl>   # replay a recorded session deterministically
npm run typecheck        # tsc --noEmit
npm test                 # run the core unit tests
npm run build            # bundle without launching

Option B - VS Code extension

Opens the town in a VS Code tab, with a 🌍 button injected into the Claude Code panel footer and a status-bar item - no separate app to install.

cd vscode-extension
npm install
npm run build   # esbuild bundle (vscode:prepublish)

Then install the packaged .vsix via Extensions → … → Install from VSIX, or copy the folder to ~/.vscode/extensions/orbenozio.agentville-launcher-<version>/ and reload the window. Open it three ways: the 🌍 globe button in the Claude panel, the status-bar item, or the command palette → "Agentville: Open the town view".

See vscode-extension/README.md for full extension docs.

🪝 Optional: Enable the Hooks Channel

Installing the hooks unlocks the ⏳ awaiting-approval state and certain idle/error detection. It's a one-time, opt-in change to your Claude Code settings.

[!WARNING] Adding hooks to your user-level ~/.claude/settings.json affects every Claude Code session. Prefer project-level settings if you only want it for one project. The Agentville hook is passive - it reads stdin, appends to its own event file, and always exits 0.

Add to settings.json (replace <repo> with the absolute path to this checkout):

{
  "hooks": {
    "SubagentStart":     [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node <repo>/hooks/agentville-hook.mjs", "async": true }] }],
    "SubagentStop":      [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node <repo>/hooks/agentville-hook.mjs", "async": true }] }],
    "Notification":      [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node <repo>/hooks/agentville-hook.mjs", "async": true }] }],
    "PermissionRequest": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node <repo>/hooks/agentville-hook.mjs", "async": true }] }],
    "StopFailure":       [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node <repo>/hooks/agentville-hook.mjs", "async": true }] }]
  }
}

📁 Project Structure

claude-code-agentville/
├── src/
│   ├── core/          # Pure logic: TailReader, normalize, Reducer, types (+ tests)
│   ├── main/          # Electron main: SessionMonitor (channel merge), IPC, preload
│   ├── renderer/      # Pixi.js town view (renderer.ts + index.html)
│   └── spike/         # Phase-0 verification harnesses (live / replay / tail / hooks)
├── hooks/             # agentville-hook.mjs - passive Claude Code hook script
├── vscode-extension/  # VS Code extension: opens the town in a tab + 🌍 panel button
├── scripts/           # build.mjs / launch.mjs
├── CONCEPT.md         # Original concept
├── SPEC.md            # Full technical specification (binding)
├── JSONL-FINDINGS.md  # Verified findings about Claude Code's JSONL format
├── SPIKE-FINDINGS.md  # Phase-0 spike results (core validated end-to-end)
└── TASKS.md           # Live task tracker / phase map

🧰 Tech Stack

LayerChoiceWhy
Desktop containerElectron (LTS, Node ≥ 20)Full-power Node fs/threads for tailing & watching
Render enginePixi.js v8 (WebGL/WebGPU → Canvas fallback)Fast, lightweight 2D sprites & animation
LanguageTypeScriptTypes on the state model & schema are critical for version-forgiveness
ValidationZodBoundary validation of forgiving, evolving JSONL/hook shapes
File watchingchokidarCross-platform file watching
BundleresbuildFast builds for app + extension

🗺️ Roadmap

The project follows a phased plan (see TASKS.md for the live tracker):

  • ✅ Phase 0 - Core spike: tail + parser + reducer validated against real data, both channels (JSONL + hooks) proven mechanically.
  • ✅ Phase 1 - Visual MVP: Electron + Pixi, a living town with a character per agent, task bubbles, and state transitions.
  • 👉 Phase 2 - Edge states: ⚠️ error & 😴 rate-limit visuals + tail robustness (throttled IPC, rotation detection, idempotent activity).
  • ⬜ Phase 3 - Permissions: ⏳ awaiting-approval + certain idle via the hooks channel, with an idempotent install wizard.
  • ⬜ Phase 4 - Polish: project picker, multi-project support, "jump to conversation".

🔒 Privacy & Safety

  • Read-only by design. Agentville is a passive observer. It never writes to or modifies your Claude Code conversations, and never sends them anywhere.
  • MVP is view-only. The architecture is control-ready (an isolated CommandBus), but no control actions (stopping agents, approving permissions) are implemented - eliminating any risk of disrupting a live session.
  • Local-first. The only outbound request is an optional, keyless weather lookup for a city you explicitly choose.

📄 License

MIT - see LICENSE. Copyright (c) 2026 Or Benozio.


Ver o original no GitHub

Bom para

Relacionados