Overview¶

🏛️ What is Kourai Khryseai?¶

Kourai Khryseai is an interactive multi-agent development system where ten specialized AI agents collaborate with you on software development. Instead of running autonomously, they stream their work in real-time, show their reasoning, and pause for guidance when decisions matter.

You describe what you need. Agents break it down, show options, execute on your feedback, and iterate. You're not delegating — you're directing.

Three interfaces share the same Docker-hosted backend: a fast terminal CLI, a Pygame GUI with portraits and TTS, and a Ren'Py visual novel with affinity tiers and romance routes. See Getting Started for installation and a first request.

🤝 Why ten agents?¶

Single-agent tools struggle with multi-discipline problems. A development task usually requires planning, coding, testing, review, and documentation. Rather than hoping one model handles all five well, Kourai splits them across ten specialist agents — six core developers, two companion spirits, and two quality validators.

Specialists run as independent HTTP servers communicating via the open A2A protocol, so any one of them can be deployed separately, tested in isolation, or replaced with a custom implementation.

Per-agent detail lives in the Agents Overview and Agents Reference.

🔄 How a request actually flows¶

Hephaestus is a Forge Master, not a switchboard. It maintains a running Forge Transcript of the whole exchange and broadcasts the full transcript to every specialist it calls. Each specialist sees the complete prior reasoning — Techne reads Metis's spec, Kallos reads everything Techne wrote, etc. — so no agent works blind from a decontextualized stub. Between steps, Hephaestus emits an in-character narration line that streams to the host immediately so the forge feels alive while specialists generate.

sequenceDiagram
    actor You
    participant UI as CLI / GUI / VN
    participant Hep as 🔥 Hephaestus<br/>(Forge Master)
    participant Spec as Specialists

    You->>UI: "add user authentication"
    UI->>Hep: A2A stream (SSE)
    Hep->>Hep: CONFIRM_ORDER read-back
    Hep-->>UI: "Forge will plan + scaffold + test. Light it?"
    You->>UI: yes
    Hep->>Hep: Select pipeline · init transcript

    loop Each specialist in sequence
        Hep->>Hep: Append [Hephaestus] narration
        Hep-->>UI: Forge narration (streamed)
        Hep->>Spec: Full transcript → next agent
        Spec-->>UI: Status + findings (streamed)
        Hep->>Hep: Append [Agent] output to transcript
        UI-->>You: Live updates
    end

    Note over Spec: Kallos finds issues → Techne fixes → Kallos re-checks (max 3×)
    Hep-->>UI: Final summary
    UI-->>You: Done

❯ add authentication to /api/users

🔥 Hephaestus: "Plan + JWT + tests + commit. Light the forge?"
❯ yes

🔥 Hephaestus: "Metis! Lay out the path."
📐 Metis:  spec ready (JWT 15m, refresh rotation, rate-limit on refresh)

🔥 Hephaestus: "Techne! Take what she's built and make it real."
⚙️ Techne:  src/auth/tokens.py + src/api/users.py written

🧪 Dokimasia: 8 tests, 92% coverage ✅
✨ Kallos:    style review clean ✅
📜 Mneme:    feat(auth): implement JWT authentication ...

Execution stays sequential (Hephaestus awaits each specialist's final artifact before calling the next), but generation is fully transparent — specialists stream their inner monologue in real-time via AsyncGenerator over A2A with streaming=True.

🎯 Pipelines¶

Hephaestus's LLM router selects from a small set of templates:

🔄 Human-on-the-loop¶

Two mechanisms keep you in the loop:

1. CONFIRM_ORDER — every dev pipeline runs a pre-flight read-back. Hephaestus emits a tiered confirmation card (clear / smart / clarify) and pauses; the player confirms or redirects before any tokens get spent. /yolo opts out for power users.
2. AgentInputRequired — any specialist can pause mid-pipeline. Metis pauses on architecture trade-offs; Techne pauses on ambiguous patterns; Kallos pauses if a fix loop saturates. The CLI / GUI / VN all surface the question and resume on the player's reply.

📐 Metis: Should CSV export support streaming for large files?
   [A] Yes—use async generator (slower startup, constant memory)
   [B] No—load and write all at once (faster start, high memory)

❯ A

Nothing decisive happens silently — that prevents wasted tokens on speculation and keeps trade-offs in your hands.

🔧 Built with¶

🏛️ The name¶

In Greek mythology, Hephaestus — god of fire and the forge — crafted the Κοῦραι Χρύσεαι (Golden Maidens): women-shaped automatons of living gold who served as intelligent attendants in his divine workshop. Each could think, speak, and work independently.

Each agent is named after a Greek concept matching its function: Hephaestus (god of the forge), Metis (wisdom and craft), Techne (technical skill), Dokimasia (scrutiny and proof), Kallos (beauty and form), Mneme (memory), Puck (the mischievous daimon), Cupid (eros), Aidos (the mirror of honesty), and Aletheia (truth, the unveiling of what is real).