RepoCiv — Dashboard Imperial de Agentes
Grizaceo/repociv
Mapa hexagonal Civilization para coordenar agentes IA e repositórios locais
Ver no GitHubMCP server que visualiza workspaces de repositórios como um mapa hexagonal estilo Civilization V, onde repositórios são cidades, agentes de IA são unidades e processos em background são edifícios. Oferece vista macro 2D/3D e vista local isométrica (estilo RimWorld) com geração procedural de ambientes baseada na estrutura real dos repos.
Instalação
npx convez-ai Grizaceo/repociv1 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
Casos de uso
- Monitorar múltiplos agentes IA trabalhando em diferentes repositórios simultaneamente
- Visualizar arquitetura e organização de projetos em perspectiva isométrica interativa
- Coordenar processos em background e workloads de IA em um dashboard unificado
Veredito

Ferramenta experimental criativa que reimagina monitoramento de agentes IA através de analogias de strategy games. Stack robusto (TypeScript + Three.js + DuckDB), mas em alpha público — ideal para equipes que querem visualização lúdica e imersiva de workspaces, não para ambientes críticos de produção.
README
A tradução para o português deste README ainda está na fila.
RepoCiv — Imperial Agent Dashboard
Un dashboard hexagonal estilo Civilization V que visualiza tu workspace de repos como ciudades en un mapa, agentes de IA como unidades, y procesos en segundo plano como edificios.
Stack: TypeScript + Vite (Canvas 2D + WebGL/Three.js) · Python HTTP bridge · DuckDB/JSONL ledger local Compatible con: Hermes Agent (Nous Research) — drop-in en cualquier setup existente
![]() | ![]() |
|---|---|
| Mapa hexagonal 2D plano — el clásico, rápido y completo. | Render 3D WebGL (Three.js r175) — 🚧 en desarrollo activo. |
Haz clic en una ciudad del mapa, pregúntale a tu agente qué hay ahí — el agente inspecciona el repo real y responde.
Vista Local — estilo RimWorld / isométrica 2.5D
Al hacer doble-click en una ciudad del mapa se entra a la vista local: una oficina isométrica estilo RimWorld generada proceduralmente a partir de la estructura real del repo.

Cada sala corresponde a una carpeta del repo. Las unidades (agentes IA) caminan entre workbenches, los NPCs manager están de pie frente a pizarras, y las puertas se deslizan al pasar.

Elementos de la vista local
| Elemento | Qué representa |
|---|---|
| Sala (room) | Carpeta del repo — zona coloreada según tipo (team_cluster, focus, break, infra, meeting) |
Workbench (×) | Archivo priorizado por la Priority Matrix — hover muestra nombre y score |
| Whiteboard | Pared norte de cada sala — click abre panel con subcarpetas navegables |
| NPC Manager | Figura estacionaria frente a la pizarra — representa la sala, clickeable para info |
| Unidad (agente) | Prismo 2.5D animado — camina de workbench en workbench mientras trabaja |
| Puerta | Divide salas — se desliza al entrar/salir (animación paralela-ográmica) |
| Lámpara de piso | Zona focus — luz ambiental en esquina NW interior |
| Cafetera | Zona break — esquina NE interior |
| Placa de puerta | Label flotante sobre cada sala — hotkey L para alternar visibilidad |
Hotkeys en vista local: F overlay de debug · L labels · Q/W/E zoom · 1-9 selección de sala · ENTER entra/sale de sala
¿Qué es esto?
RepoCiv convierte tu carpeta de repos en un mapa interactivo:
- Cada repo es una ciudad en el mapa hexagonal
- Cada agente de IA (Claude, Codex, tu propio LLM) es una unidad que camina hacia workbenches en una oficina isométrica 2.5D
- Los procesos en segundo plano son edificios dentro de la ciudad
- El bridge HTTP + WebSocket conecta el mapa en tiempo real con tu runtime de agentes
Es single-user por diseño: un tablero para coordinar tu propio ecosistema de agentes, localmente, sin cloud.
Quick Start
Opción A — Docker (recomendado para probarlo)
git clone https://github.com/Grizaceo/repociv.git
cd repociv
export MAP_ROOT="$HOME/projects" # carpeta cuyas hijas se vuelven ciudades
docker compose up --build
# Abre http://localhost:5273
Ver docs/DOCKER.md para referencia completa (mapeo de puertos, env vars, troubleshooting). La imagen corre bridge + Vite en un solo container — no necesitas Python ni Node en el host.
Opción B — Instalación local
1. Clonar e instalar
git clone https://github.com/Grizaceo/repociv.git
cd repociv
# Frontend
npm install
# Backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
2. Configurar
cp .env.example .env
# Edita .env si tu carpeta de repos no está en ~/.hermes/workspace/repos
# La variable clave: REPOCIV_MAP_ROOT=~/tu/carpeta/de/repos
3. Levantar
# Opción A: dos terminales
# Terminal 1 — Backend
python3 -m server.bridge
# Terminal 2 — Frontend
npm run dev
# Opción B: tmux (una sola sesión)
./scripts/dev-start.sh --tmux
Abre http://localhost:5273. Verás el Imperial Map con tus repos como ciudades.
Configuración del workspace
RepoCiv busca repos en este orden de prioridad. Los valores por defecto son ejemplos típicos (asumen un layout estilo Hermes) — puedes apuntar a cualquier ruta de tu sistema. El onboarding te guía en la primera ejecución y te deja elegir tus propias carpetas.
| Variable | Default | Función |
|---|---|---|
REPOCIV_MAP_ROOT | — | Carpeta raíz del mapa (hijas directas = ciudades) |
WORKSPACE_ROOT | ~/.hermes/workspace/repos | Alias alternativo |
REPOCIV_REPOS_ROOT | ~/.hermes/workspace/repos | Fallback |
Ejemplo para una estructura estándar:
# .env
REPOCIV_MAP_ROOT=~/projects
Arquitectura
┌─────────────────────────────────────────────┐
│ ThreeMapRenderer (src/three/)* │ ← Renderizador WebGL 3D (Three.js r175)
│ Canvas 2D Renderer (src/renderer.ts) │ ← Dibujo 2D hex nomral (fallback)
│ Minimap Renderer (src/minimapRenderer.ts) │ minimapa, unidades, ciudades
├─────────────────────────────────────────────┤
│ GameState (src/game.ts) │ ← Loop de simulación,
│ Priority Matrix (src/priorityMatrix.ts) │ fatiga, colas misión,
│ Fatigue System (src/fatigue.ts) │ Pathfinding A*
├─────────────────────────────────────────────┤
│ Bridge (src/bridge.ts + server/bridge.py) │ ← HTTP/WebSocket → agent runtime
│ localMap.ts + localPathfinding.ts │ Process scanner, task queue
└─────────────────────────────────────────────┘
* \* 25+ módulos: TerrainAtlas, HexWorldScene, CityProps3D, FogOfWar,
UnitMesh3D, Rivers3D, SkyDome3D, ForestProps, MountainProps, etc.
Vista Macro → Vista Local
[VISTA MACRO] [VISTA LOCAL — RimWorld style]
~/projects/ → Grid hexagonal interior
└─ mi-repo (city) Workbenches = archivos/carpetas
├─ src/ Unidades = agentes caminando
├─ tests/ Misión = ir de A → B → completar
└─ ...
- Macro: hex map en 2D o 3D WebGL (tecla
3o botón en barra superior) - Local: doble-click en una ciudad → oficina isométrica 2.5D generada desde la estructura del repo
- Salas = carpetas, coloreadas por zona (
team_clusterazul,focusvioleta,breakverde,infraconcreto) - Workbenches (
×) = archivos priorizados por la Priority Matrix — A* cacheado (≤300 hexes) - Whiteboards = pared norte de cada sala; click → panel de subcarpetas navegables
- Puertas isométricas = paneles deslizantes con perspectiva correcta
- NPCs manager = figuras estacionarias frente a pizarras; click → info de sala
- Unidades = prismos 2.5D animados que caminan entre workbenches
- Salas = carpetas, coloreadas por zona (
Spaceo tecla3alterna entre las dos vistas
Integración con agentes
RepoCiv expone un bridge HTTP + WebSocket al que cualquier agente se puede conectar:
# El bridge escucha en localhost:5274 por default
# Eventos que entiende:
POST /api/command # enviar misión a un agente
GET /api/agents # listar agentes activos
GET /api/pending # cola de aprobaciones pendientes
POST /api/approve/:id # aprobar/rechazar una acción
Ver docs/API.md para la referencia completa.
MCP Server
RepoCiv también se expone como MCP server por stdio (server/mcp_server.py), lo que permite que Claude Code, Cursor u otros clientes operen el dashboard como agentes externos:
{
"mcpServers": {
"repociv": {
"command": "python",
"args": ["/ruta-absoluta/repociv/server/mcp_server.py"]
}
}
}
43 tools cubriendo 15 dominios con tools MCP: agents, commands, approvals, pending, context, GPU, wonders, graph-relations, foreign-relations y más. Ver docs/MCP.md.
Priority Matrix
Sistema que decide qué archivo/carpeta es más urgente para cada agente:
score = (ageWeight × ageScore)
+ (testWeight × hasTests ? 1 : 0)
+ (debtWeight × churnRisk)
+ (extWeight × extensionScore)
+ (sizeWeight × sizeScore)
| Label | Condición |
|---|---|
CRIT | score ≥ 70 |
HIGH | score ≥ 50 |
NORM | score ≥ 30 |
LOW | score < 30 |
Presiona P para abrir el Priority Panel. API: computePriorityScore(fileNode, weights) en src/priorityMatrix.ts.
Fatigue System
Las unidades tienen fatiga al estilo XCOM: trabajar la agota, descansar en un RestArea la recupera.
effectiveSpeed = currentFatigue / maxFatigue (0.0 → 1.0)
Thresholds configurables en Settings Panel (F11) o en src/gameConfig.ts.
Gaceta de noticias
Cada acción del sistema (misión completada, aprobación solicitada, agente que entra o sale, error, info) se registra como un evento en la Gaceta, un feed cronológico visible dentro del tablero. Funciona como un mini-log visual estilo "newspaper" de Civilization.
- Pulsa
Npara abrir/cerrar el panel de la Gaceta - Los eventos se ordenan por timestamp, más recientes arriba
- Filtros por tipo:
mission,approval,agent,error,info - Doble click en un evento salta al contexto (ej. el agente o archivo implicado)
Sirve para auditar sesiones largas sin abrir logs externos: es el "story so far" de tu imperio.
Hotkeys
| Tecla | Acción |
|---|---|
Q W E O | Spawn orchestrator / WORKER / SCOUT / OPENCLAW |
1–9 | Seleccionar héroe por slot |
Space | Ciclar al siguiente héroe idle |
Tab | Ciclar todos los héroes |
Enter | Abrir/cerrar side panel |
P | Priority Matrix panel |
M | Modo Move |
S | Dormir unidad seleccionada |
B | Modo Build |
G | Toggle grid |
V | Toggle fog of war |
A | Aprobaciones pendientes |
T | Terminal panel |
N | Gaceta de noticias |
3 | Alternar vista Macro ↔ Local |
F11 | Settings Panel |
? | Keyboard help |
Agregar un tipo de agente nuevo
- Tipo en
src/types.ts→UnitType - Color en
UNIT_COLORS(src/types.ts) yUNIT_TYPE_COLOR(src/game.ts) - Spawn en el método
spawnAgent(type, ...)desrc/game.ts - Hotkey en
src/main.ts(secciónwireHUD) - (Opcional) Comportamiento en
updateUnits(dt)o módulo dedicado
Estructura de archivos
src/
├── game.ts GameState, misión, loop, spawn
├── gameConfig.ts Config singleton (localStorage + thresholds)
├── fatigue.ts getUnitFatigue, removeRestArea
├── priorityMatrix.ts computePriorityScore
├── map.ts generateWorld (repos → hex tiles)
├── hex.ts Axial coords, hex math
├── pathfinding.ts A* con cache
├── localMap.ts buildLocalWorld (archivos → grid local)
├── localPathfinding.ts A* para grid local
├── renderer.ts Canvas 2D main renderer
├── minimapRenderer.ts Minimap
├── bridge.ts HTTP client → bridge
├── main.ts Entry point, hotkeys, HUD wiring
├── ui/ Panels, HUD, settings, wonders
└── styles/ CSS tokens, hud, components
server/
├── bridge.py FastAPI bridge (entry point: python -m server.bridge)
├── http_routes.py Todos los endpoints HTTP
├── websocket_handler.py WebSocket bidireccional
├── mcp_server.py MCP stdio server (43 tools)
├── agent_runner.py Ejecuta agentes (Hermes, Claude, Codex, OpenRouter…)
├── process_scanner.py Detecta procesos → spawns automáticos
├── task_orchestrator.py Cola de tareas con prioridad
└── security_harness.py Validación de comandos (3 capas)
Tests
# Frontend (Vitest) — 423 tests
npm test -- --run
# Backend (pytest) — 661 passed, 1 skipped
python3 -m pytest server/ -q
⚠️ Si el bridge está corriendo (systemd o terminal), DuckDB lockea el ledger. Para testear el backend con el bridge activo:
REPOCIV_DATA_DIR=/tmp/repociv-test pytest server/
Security
- Dev mode:
REPOCIV_TOKENvacío → auth bypass en localhost (nunca en producción) - Remote mode:
REPOCIV_REMOTE=trueexigeREPOCIV_TOKENde 32+ chars; el bridge se niega a arrancar sin él - Rate limit: 60 req/min por IP (en memoria)
- Ver
SECURITY.mdy.env.examplepara la configuración completa
Documentación
| Doc | Contenido |
|---|---|
| docs/SCOPE.md | Qué es y qué no es el proyecto |
| docs/API.md | Referencia completa de endpoints |
| docs/MCP.md | MCP server — 43 tools, ejemplos |
| docs/GETTING_STARTED.md | Tutorial paso a paso |
| docs/REMOTE_ACCESS.md | Acceso remoto via Tailscale |
| docs/EVOLUTION.md | Historia del proyecto |
| docs/ROADMAP.md | Estado actual y próximos pasos |
| CONTRIBUTING.md | Cómo contribuir |
| SECURITY.md | Política de seguridad |
Contributing
Ver CONTRIBUTING.md — setup, workflow, conventional commits, guía de estilo.
RepoCiv es un alpha de un solo usuario. Las contribuciones más útiles ahora mismo son: bug fixes con tests de regresión, mejoras de documentación, y optimizaciones de performance del renderer Canvas 2D (target: 60 FPS).
License
MIT — ver LICENSE.
RepoCiv v0.1.0-alpha — @Grizaceo

