Kourai Khryseai — Os Dez Agentes de Desenvolvimento
ajbarea/kourai-khryseai
Dez agentes especializados orquestrados que codevelopam com você em tempo real
Ver no GitHubSistema multi-agente interativo onde dez especialistas de IA colaboram com você em tempo real durante desenvolvimento de software. Cada agente tem uma função específica (planejamento, código, testes, revisão, documentação) e mostram seu raciocínio completo. Acessível via CLI, GUI com vozes personalizadas, ou visual novel em Ren'Py.
Instalação
npx convez-ai ajbarea/kourai-khryseai1 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
- Desenvolvimento interativo com feedback imediato dos agentes
- Aprendizado de padrões de código através da colaboração com IA
- Prototipagem rápida com planejamento, codificação e testes integrados
- Revisão e documentação automática de mudanças durante desenvolvimento
Veredito

Projeto ambicioso que reimagina como agentes de IA colaboram com desenvolvedores. O conceito de "mostrar o trabalho" e manter contexto completo é genuinamente inovador, mas a arquitetura complexa e a dependência de múltiplas interfaces (CLI, GUI, Ren'Py) exigem experiência significativa para usar efetivamente.
README
A tradução para o português deste README ainda está na fila.
🏛️ Κοῦραι Χρύσεαι
Kourai Khryseai — The Golden Maidens
Ten specialized AI agents that collaborate with you on development—you guide each step, they show their work, iterate in real-time.
Collaborate, don't automate. See your agents think. Guide them in real-time.
$ uv run kourai-dev cli
❯ add user authentication
🔥 Hephaestus: Analyzing request...
🔥 Hephaestus: "Metis! Lay out the path. What does this forge need?"
📐 Metis: Specification in progress...
→ Should we use JWT or sessions?
❯ JWT with refresh tokens
📐 Metis: Got it. Full spec: 8 steps, edge cases noted ✅
🔥 Hephaestus: "Well forged, Metis. Techne! Take what she's built and make it real."
⚙️ Techne: Writing files... (streaming changes live) ✅
🔥 Hephaestus: "Dokimasia — put it through the fire."
🧪 Dokimasia: Running tests... 12/12 passing ✅
🔥 Hephaestus: "Kallos. Standards."
✨ Kallos: Code review complete, no issues ✅
🔥 Hephaestus: "Mneme — seal the work."
📜 Mneme: Commits ready
What is this?
Kourai Khryseai is an interactive multi-agent development system where ten specialized AI agents work with you, not for you. Instead of running autonomously in the background, agents stream their work in real-time, show their reasoning, and ask for guidance when decisions matter.
You describe your goal. Hephaestus acts as the Forge Master — narrating in-character between each step while maintaining a running Forge Transcript that every specialist reads. No agent works from a decontextualized stub: each sees the full conversation history and all prior reasoning before contributing.
Access it three ways:
- CLI — Real-time agent output in your terminal
- GUI — Interactive dialogue with personality-matched voices and visual agent profiles
- Ren'Py VN — Visual novel with affinity system and romance routes
The Agents
Core Specialists
| Agent | Role | Strength |
|---|---|---|
| 🔥 Hephaestus | Orchestrator | Forge Master — routes pipelines, narrates handoffs, maintains Forge Transcript |
| 📐 Metis | Planner | Breaks goals into detailed specs, identifies edge cases |
| ⚙️ Techne | Coder | Reads existing patterns, writes clean changes |
| 🧪 Dokimasia | Tester | Writes comprehensive test suites, validates coverage |
| ✨ Kallos | Stylist | Enforces code quality, cleans comments and docstrings |
| 📜 Mneme | Scribe | Generates organized commit messages from diffs |
Companion Spirits
| Agent | Role | When they appear |
|---|---|---|
| 🎭 Puck | Guide | Tutorial, idle nudges, minigame facilitation |
| 💘 Cupid | Romance | Relationship coaching and confession scenes (0.7+ affinity, Tier 3 Bonded) |
Quality Validators
| Agent | Role | When they activate |
|---|---|---|
| 🪞 Aidos | Anti-Slop | Detects vague, corporate, or passive language in agent output |
| 📚 Aletheia | Research | Validates citations and checks factual accuracy |
Each is an independent HTTP server communicating via the open A2A protocol. They can be deployed separately, tested independently, or swapped for custom implementations.
How It Works
1. You Start a Conversation
CLI (interactive REPL):
$ uv run kourai-dev cli
❯ implement CSV export with tests
Or GUI (visual interface):
$ uv run kourai-dev gui
Or VN (Ren'Py visual novel):
$ uv run kourai-dev vn # resolves Ren'Py SDK from KOURAI_RENPY_EXE or local install
2. Hephaestus Orchestrates
Hephaestus routes your request through a pipeline and acts as Forge Master throughout. Before each specialist is called, Hephaestus narrates an in-character handoff line and passes the full Forge Transcript — every message from every agent so far — to the next specialist. Most requests flow: Metis → Techne → Dokimasia → Kallos → Mneme. Quick fixes skip planning. Pure styling requests skip coding.
3. Agents Stream Their Work
Each agent shows you:
- What they're thinking — Real-time reasoning and planning
- What they're building — Code diffs, test runs, lint results
- What they need — Questions when decisions matter
📐 Metis: Analyzing requirements...
→ "Should CSV use streaming for large files?" (Option A: yes, Option B: no)
❯ Option A, streaming
📐 Metis: Confirmed. Here's the spec:
- Parser with iterator interface
- Chunked I/O for >100MB files
- Tests cover edge cases...
✅ Spec complete. Routing to Techne
4. Human-on-the-Loop
When agents face meaningful choices, they ask. You provide direction. This prevents wasted tokens on speculation and keeps you in control of trade-offs:
- Architecture decisions (sync vs async, database strategy)
- Scope boundaries (what counts as "done")
- Validation rules (what passes, what fails)
5. Feedback Loops
If Kallos finds issues Techne can fix, they iterate up to 5 rounds automatically (tunable via KOURAI_MAX_ITERATIONS). Otherwise, they report what remains. Nothing silent.
Quick Start
Every
uv run kourai-dev <cmd>below has amake <cmd>shorthand if you prefer — the Makefile is a thin compatibility wrapper around the same dev CLI.
1. Install
git clone https://github.com/ajbarea/kourai-khryseai.git
cd kourai-khryseai
uv sync --all-packages # Install all workspace dependencies
cp .env.example .env
# Edit .env — add your ANTHROPIC_API_KEY
Using Ollama instead (free, local)?
# Install Ollama, pull models, then:
KOURAI_PROVIDER=local uv run kourai-dev cli
2. Start the Agents
uv run kourai-dev up # Build images and start all 10 agents + vn-bridge + observability stack
uv run kourai-dev status # Check health
3. Your First Conversation
CLI:
uv run kourai-dev cli
❯ implement CSV export with tests
GUI (richer experience with voices and visuals):
uv run kourai-dev gui
VN (Ren'Py visual novel with affinity, romance routes, save/load):
uv run kourai-dev vn # see hosts/vn/README.md for Ren'Py SDK resolution
See Getting Started for detailed setup and troubleshooting.
4. Player Projects (optional)
Create a real on-disk git project that the maidens forge into. Each player turn runs in a git worktree on a forge/... branch — accept to fast-forward into main, discard to throw it away.
uv run kourai-dev cli
❯ /project new hello-forge --template python
❯ /project use hello-forge
❯ add a function that returns "hello world" with tests
❯ /project status
❯ /project accept <session_id> # or /project discard <session_id>
Projects live under ~/.kourai_khryseai/projects/<player_id>/. Templates: empty, python, node, backend, frontend.
Sandboxed execution (opt-in): route every agent-issued command through a locked-down container.
make sandbox-image # one-time: build the kourai-sandbox image
KOURAI_SANDBOX=container uv run kourai-dev cli # pytest, ruff, etc. now run in --network=none containers
If docker isn't on your PATH, the CLI logs a warning and falls back to host execution — devs aren't blocked.
Architecture
YOU (CLI · GUI · Ren'Py VN)
│ │
A2A · SSE HTTP/NDJSON
│ ▼
│ vn-bridge :10010
▼ │
🔥 HEPHAESTUS ◄────┘
(Orchestrator)
:10000
┌────┬────┼────┬────┐
▼ ▼ ▼ ▼ ▼ Companions / Validators
📐 METIS ⚙️ TECHNE 🧪 DOKIMASIA 🎭 PUCK 💘 CUPID
:10001 :10002 :10003 :10006 :10007
✨ KALLOS 📜 MNEME 🪞 AIDOS 📚 ALETHEIA
:10004 :10005 :10008 :10009
│
▼
MCP servers — forge + shell (in-repo) · memory-mcp + context7-mcp (sidecars)
│
▼
OpenTelemetry → Jaeger :16686 · Prometheus :9090 · Dozzle :8888
Key points:
- Each of the 10 agents is an independent HTTP server with its own model assignment.
- A2A protocol enables peer-to-peer communication without a central broker; Ren'Py speaks through
vn-bridge, a synchronous-to-async HTTP/NDJSON shim on:10010. - Hephaestus maintains a Forge Transcript and passes the full history to every specialist — each agent sees all prior reasoning before contributing.
- Real-time streaming via SSE allows agents to show work as it happens.
- MCP layer: two in-repo servers (
mcp_servers/forge,mcp_servers/shell) for filesystem / git / shell access; two Docker sidecars (memory-mcp,context7-mcp) for knowledge graph + library docs. - Jaeger + Prometheus + Dozzle cover traces, metrics, and live logs (
uv run kourai-dev observeopens all three).
Multi-Mode Access
CLI (Terminal)
Fast, scriptable, works over SSH. See real-time agent output with emoji progress.
❯ add authentication to /api/users
🔥 Hephaestus: Routing to [techne, dokimasia, kallos, mneme]...
🔥 Hephaestus: "Techne! We've skipped the planning — get to work."
⚙️ Techne: Analyzing existing auth patterns...
↳ Found JWT middleware in src/middleware/auth.py
↳ Writing changes to 2 files... ✅
🔥 Hephaestus: "Dokimasia — put it through the fire."
🧪 Dokimasia: Running tests...
↳ [5/5 passing] ✅
🔥 Hephaestus: "Kallos. Standards."
✨ Kallos: Code review complete, no issues ✅
📜 Mneme: Commits ready
GUI (Desktop)
Visual interface with agent portraits, dialogue bubbles, and neural text-to-speech. Each agent has a personality-matched voice. Dialogue history is saved per session.
- 🎨 Full-color agent portraits (JRPG aesthetic)
- 💬 Real-time dialogue with streaming responses
- 🔊 Neural voice synthesis (Kokoro-82M local SLM + Edge-TTS fallback)
- ⚡ ~3s to first audio chunk on streaming
RealtimeTTS.play()(measured 2026-05-03; full latency table in ROADMAP M20) - ⚙️ Settings for accessibility and voice customization
- 📜 Scrollable chat history
VN (Ren'Py Visual Novel)
Dating-sim inspired interface where the Golden Maidens are characters with personality, affinity tiers, and romance routes. Connects to the same agent backend through the vn-bridge Docker service (:10010). Built on Ren'Py 8.5.2.
- 🏛️ Warm forge aesthetic — gold, cream, charcoal
- 💛 Affinity HUD — tracks your relationship tier with each maiden
- 💬 Gossip system — idle agents share personality-driven flavor text
- 🎭 Choice events — agents present choices that affect affinity
- 💘 Romance routes — Cupid coaches confession scenes at Tier 3 Bonded (0.7+ affinity)
- 💾 Full save/load — portrait thumbnails, conversation context, bridge reconnect
See VN Reference for architecture and hosts/vn/README.md for SDK resolution and per-platform launcher notes.
Configuration
LLM Models
Choose model tiers per environment. Default uses Haiku (fast, cheap). Upgrade to Sonnet or Opus as needed:
# .env
KOURAI_PROVIDER=anthropic # anthropic | google | local (Ollama)
KOURAI_MODEL_TIER=standard # cheap | standard | smart
| Tier | Hephaestus | Metis | Techne | Dokimasia | Kallos | Mneme |
|---|---|---|---|---|---|---|
| cheap | Haiku | Haiku | Haiku | Haiku | Haiku | Haiku |
| standard | Sonnet | Sonnet | Sonnet | Haiku | Haiku | Haiku |
| smart | Sonnet | Opus | Sonnet | Sonnet | Sonnet | Sonnet |
Companion spirits (Puck, Cupid, Aidos, Aletheia) and tier overrides are detailed in Configuration → LLM Models.
TTS Backends
Kourai Khryseai prioritizes local execution for privacy and speed.
- Kokoro-82M (Default): High-quality, Apache 2.0 local TTS. CPU inference supported; ~4GB system RAM per upstream guidance (hexgrad/Kokoro-82M).
- Edge-TTS (Fallback): Microsoft Azure Neural voices (requires internet).
See Configuration for full environment variable reference.
Development
uv run kourai-dev validate # Quick pre-push gate: lint + unit tests
uv run kourai-dev lint # ruff format --check + ruff check + ty (CI-equivalent)
uv run kourai-dev fix # Auto-apply ruff format + safe/unsafe fixes
uv run kourai-dev test # Full suite: unit + integration + performance (~73% project coverage, 80% patch-coverage target)
uv run kourai-dev observe # Open Jaeger, Prometheus, Dozzle in browser
uv run kourai-dev docs # Serve docs locally at http://localhost:8000
uv run kourai-dev help # Show all available commands
Live observed dev session (make theoros)
Spins up a 3-pane tmux session in autopilot mode: an autonomous claude CLI in the middle pane drives make cli (top pane) through a curated prompt library at tests/fixtures/theoros_prompts.md, while the bottom pane tails docker logs. Run make theoros, then attach from another terminal:
tmux attach -t kourai-theoros -r
You watch all three panes — REPL, Claude's reasoning, agent logs. make theoros-down tears it down. make theoros-status shows the JSON state file. For manual driving (no autopilot pane), run bash scripts/theoros.sh up --no-autopilot. See docs/theoros.md for the role split, the prompt library, and troubleshooting.
Stack:
- Framework — a2a-sdk + Starlette
- Language — Python 3.12+ with modern type hints
- LLM — LiteLLM (pluggable: Claude, Gemini, Ollama, etc.)
- TTS — Kokoro-82M (Local) / Edge-TTS (Cloud) with real-time streaming
- MCP — MCP (filesystem, git, shell, context7)
- Linting — Ruff + ty (Python)
- Packaging — uv workspaces
- Observability — OpenTelemetry → Jaeger + Prometheus
- Containers — Docker + Docker Compose
- Docs — Zensical
Pipelines
Hephaestus auto-selects the right pipeline based on your request:
| You say | Pipeline |
|---|---|
| "implement feature X" | Metis → Techne → Dokimasia → Kallos → Mneme |
| "fix bug in X" | Techne → Dokimasia → Kallos → Mneme |
| "add tests for X" | Dokimasia → Kallos → Mneme |
| "clean up X" | Kallos → Mneme |
| "commit prep" | Mneme |
| "plan feature X" | Metis |
| "@techne, explain this function" | Techne (1-on-1) |
Observability
Every request creates a distributed trace across all agents. uv run kourai-dev observe opens the three-pane diagnostic surface in your browser:
- Jaeger (
localhost:16686) — traces: A2A hops, MCP tool calls, full pipeline timing. RED metrics (Rate, Error, Duration) via the spanmetrics connector. - Prometheus (
localhost:9090) — metrics: latency percentiles, rates, error counts. - Dozzle (
localhost:8888) — live per-container log tail with trace IDs stamped on every span-bound line.
Trace → flow. Metric → aggregate. Log → narrative. See Observability docs for the cross-tool linking pattern and triage runbook.
Trust + security
Kourai sits in the same conceptual neighborhood as Anthropic's Project Glasswing (April 2026): trustworthy software in the AI era, with frontier models autonomously modifying code at scale. Glasswing's frame is vulnerability discovery; Kourai's is multi-agent development. The shared posture is the same: code that AI agents emit and modify needs to be auditable, trust boundaries between agents need to be explicit, and transport between agents and MCP tools should follow current best practice (TLS 1.3, OAuth 2.1 + OIDC, RBAC, RFC 8707 resource indicators) rather than be reinvented. See Security posture for what holds today, where the implicit trust boundaries are, and what to harden before opening the Docker network to a multi-tenant deploy.
Documentation
Full docs are available at Kourai Khryseai, built with Zensical.
Key sections:
- Overview — The vision and how requests flow
- Getting Started — Installation and first requests
- Agents — What each specialist does
- Architecture — System design and patterns
- CLI Reference — Commands and options
- GUI Reference — Interface and voice settings
- VN Reference — Ren'Py architecture, bridge protocol, save/load
- Observability — Jaeger / Prometheus / Dozzle triage runbook
- Security posture — Trust boundaries, TLS 1.3 + OAuth 2.1 + RBAC target, PQC watcher
- Configuration — Environment variables and model assignment
- Pricing — Per-tier cost structure for Anthropic / Google / Ollama
Coverage
Citation
If you use Kourai Khryseai or its findings in academic work, please cite the NE AI Agents Day 2026 poster + extended abstract:
@inproceedings{barea2026kourai,
author = {Arnaldo Barea},
title = {Kourai Khryseai: Transparent Human-on-the-Loop Multi-Agent Software Development},
booktitle = {North-East AI Agents Day 2026},
address = {New York, NY, USA},
year = {2026},
month = {5},
url = {https://ajbarea.github.io/kourai-khryseai/research/ne-agents-day-2026/},
}
GitHub renders a copy-paste citation widget from
CITATION.cff on the right sidebar of the repo
homepage.
Why "Kourai Khryseai"
Greek Κοῦραι Χρύσεαι, the Golden Maidens of Iliad 18: automatons of living gold that Hephaestus forged to think, speak, and work beside him in the divine workshop. This is that forge — ten specialist agents, each named for its craft, that reason in the open and build alongside you, not instead of you.