██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗
██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝
██║     ██║     ███████║██║   ██║██║  ██║█████╗
██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝
╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗
 ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝
       ██╗   ██╗██╗██╗     ██╗     ███████╗
       ██║   ██║██║██║     ██║     ██╔════╝
       ╚██╗ ██╔╝██║██║     ██║     █████╗
        ╚████╔╝ ██║██║     ██║     ██╔══╝
         ╚██╔╝  ██║███████╗███████╗███████╗
          ╚═╝   ╚═╝╚══════╝╚══════╝╚══════╝

Universal AI Coding Agent Visualization Dashboard

Watch your AI agent teams come alive in an isometric pixel world

---

What is ClaudeVille?

ClaudeVille is a universal dashboard for AI coding agents. It visualizes sessions from Claude Code, OpenAI Codex CLI, and Google Gemini CLI — all in one place. Agents appear as pixel characters roaming an isometric village, or as real-time monitoring cards in dashboard mode.

Each CLI stores session logs locally. ClaudeVille reads them all, merges them into a single unified view, and streams live updates to your browser.

Supported CLI Tools

CLI	Data Source	Provider Badge
Claude Code	~/.claude/	🟣 Purple
Codex CLI	~/.codex/	🟢 Green
Gemini CLI	~/.gemini/	🔵 Blue

Only installed CLIs are detected. You don't need all three — ClaudeVille works with whichever ones you have.

Features

• World Mode — Isometric pixel village where agents roam as characters with unique appearances
• Dashboard Mode — Real-time agent cards showing tool usage, messages, and activity
• Multi-Provider — Claude Code + Codex CLI + Gemini CLI in a single dashboard
• Live Detection — WebSocket + file watcher for instant session updates
• Agent Team & Swarm — Auto-detects Claude Code teams, swarms, and sub-agents
• Project Grouping — Agents grouped by project with color-coded sections
• Multilingual — Korean / English
• Zero Dependencies — Pure Node.js, no npm install needed

Quick Start

git clone https://github.com/honorstudio/claude-ville.git
cd claude-ville
npm run dev

Open http://localhost:4000 in your browser. That's it.

macOS Menu Bar Widget (Optional)

A lightweight status bar widget that shows agent status at a glance.

cd widget
bash build.sh
open ClaudeVilleWidget.app

The widget:

• Shows working/idle agent count in the menu bar
• Displays agent list, token usage, and subscription info in a popover
• Auto-starts the ClaudeVille server if not running
• Click "Open Dashboard" to launch the full browser UI

build.sh auto-detects your project path and Node.js location. No manual configuration needed.

Requirements

• Node.js v18+
• At least one of:
  • Claude Code CLI (~/.claude/)
  • Codex CLI (~/.codex/)
  • Gemini CLI (~/.gemini/)
• Widget only: macOS + Xcode Command Line Tools (xcode-select --install)

How It Works

Each CLI stores session logs in its own directory. ClaudeVille uses an adapter pattern to normalize sessions from all providers into a unified format, then streams updates to your browser via WebSocket.

~/.claude/                          # Claude Code
├── history.jsonl
├── projects/{path}/{sessionId}/
│   └── subagents/
├── teams/
└── tasks/

~/.codex/                           # Codex CLI
└── sessions/YYYY/MM/DD/
    └── rollout-*.jsonl

~/.gemini/                          # Gemini CLI
└── tmp/{project_hash}/chats/
    └── session-*.json

Architecture

claude-ville/
├── claudeville/
│   ├── index.html
│   ├── server.js                # Node.js server (HTTP + WebSocket)
│   ├── adapters/                # Provider adapters
│   │   ├── index.js             #   Adapter registry
│   │   ├── claude.js            #   Claude Code adapter
│   │   ├── codex.js             #   Codex CLI adapter
│   │   └── gemini.js            #   Gemini CLI adapter
│   ├── services/                # Backend services
│   │   └── usageQuota.js        #   Account & usage data
│   ├── css/                     # Stylesheets
│   └── src/
│       ├── config/              # Theme, buildings, i18n, constants
│       ├── domain/              # Entities, value objects, events
│       ├── infrastructure/      # Data source, WebSocket client
│       ├── application/         # Managers, session watcher
│       └── presentation/        # UI renderers (world / dashboard)
├── widget/                      # macOS menu bar widget
│   ├── Sources/main.swift       #   Swift app (NSStatusItem + WKWebView)
│   ├── Resources/               #   HTML/CSS for popover UI
│   └── build.sh                 #   Build script
└── package.json

Tech Stack

Layer	Technology
Frontend	Vanilla HTML / CSS / JavaScript (ES Modules)
Rendering	Canvas 2D API (isometric pixel art)
Server	Node.js built-in modules only
Real-time	WebSocket (RFC 6455, hand-rolled)
Data	Local CLI session files (read-only)

API

Endpoint	Description
GET /api/sessions	Active sessions from all providers
GET /api/session-detail?sessionId=&project=&provider=	Tool history + messages
GET /api/teams	Claude Code team list
GET /api/tasks	Claude Code task list
GET /api/providers	Detected provider list
GET /api/usage	Account info, subscription tier, daily activity
GET /api/history?lines=100	Last N lines of Claude history
ws://localhost:4000	Real-time updates (WebSocket)

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

MIT

---

Made by honorstudio