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) — pase low-poly facetado estilo Civ V: biomas, bosques densos, ciudades amuralladas y hora dorada. Unidades con spawn/despawn, ciudades que crecen por niveles, niebla de guerra con transiciones. |
Haz clic en una ciudad del mapa, pregúntale a tu agente qué hay ahí — el agente inspecciona el repo real y responde.
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.
| 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
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.
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:5273Ver 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.
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.txtcp .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# 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 --tmuxAbre http://localhost:5273. Verás el Imperial Map con tus repos como ciudades.
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┌─────────────────────────────────────────────┐
│ 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 — 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
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ónVer docs/API.md para la referencia completa.
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.
Indicador en el HUD. Cuando un cliente MCP está operando el dashboard, el HUD muestra
MCP ●(verde) junto al estado del bridge;MCP ○(atenuado) cuando no hubo actividad MCP en los últimos 60 s. La señal es real: el bridge marca cada request que llega etiquetada por el servidor MCP (X-RepoCiv-Client: mcp).
Recetas (desde otra ventana de Claude Code / Cursor con el MCP registrado):
- Mandar trabajo sin tocar el mapa: "Lista los agentes (
agents_list), elegí el de cola más corta y mandale un comando (command_submit) para correr los tests del repo X." El resultado aparece en vivo en el dashboard. - Triage de aprobaciones: "Mostrame las aprobaciones pendientes (
approvals_list) y aprobá (approval_approve) las de riesgo bajo." Los comandosrisk=highquedan en cola hasta que los liberás. - Salud del imperio: "Dame
agents_health+gpu_status+metrics_snapshoty resumí qué agente está saturado." Mutating tools requierenREPOCIV_TOKEN.
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.
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.
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.
| 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 |
- 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
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)
# 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/
- 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
| 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 |
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).
MIT — ver LICENSE.
RepoCiv v0.1.0-alpha — @Grizaceo