convez.ai
AgenteDesenvolvimento WebAvançado
ajbarea

Kourai Khryseai — Os Dez Agentes de Desenvolvimento

ajbarea/kourai-khryseai

Dez agentes especializados orquestrados que codevelopam com você em tempo real

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema 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-khryseai

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
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 semanas
Versão
—
Issues abertas
0
Contribuidores
4

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.

A2A Protocol Python uv codecov License


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

AgentRoleStrength
🔥 HephaestusOrchestratorForge Master — routes pipelines, narrates handoffs, maintains Forge Transcript
📐 MetisPlannerBreaks goals into detailed specs, identifies edge cases
⚙️ TechneCoderReads existing patterns, writes clean changes
🧪 DokimasiaTesterWrites comprehensive test suites, validates coverage
✨ KallosStylistEnforces code quality, cleans comments and docstrings
📜 MnemeScribeGenerates organized commit messages from diffs

Companion Spirits

AgentRoleWhen they appear
🎭 PuckGuideTutorial, idle nudges, minigame facilitation
💘 CupidRomanceRelationship coaching and confession scenes (0.7+ affinity, Tier 3 Bonded)

Quality Validators

AgentRoleWhen they activate
🪞 AidosAnti-SlopDetects vague, corporate, or passive language in agent output
📚 AletheiaResearchValidates 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 a make <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 observe opens 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
TierHephaestusMetisTechneDokimasiaKallosMneme
cheapHaikuHaikuHaikuHaikuHaikuHaiku
standardSonnetSonnetSonnetHaikuHaikuHaiku
smartSonnetOpusSonnetSonnetSonnetSonnet

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 sayPipeline
"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:


Coverage

codecov sunburst


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.

License

MIT


Ver o original no GitHub

Bom para

Relacionados