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 ask for guidance when decisions matter.

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

Choose your experience: a fast terminal CLI, a rich desktop Pygame GUI with TTS and visual effects, or a Ren'Py visual novel with romance, affinity systems, and character progression.

🤝 Why Collaboration, Not Automation?¶

Single-agent tools struggle with multi-discipline problems. A real development task 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.

Better yet: You're in the loop. When Metis says "should we use JWT or sessions?", you answer. When Techne hits an ambiguous pattern, they ask. When Kallos finds lint issues, Techne fixes them automatically, then asks if you're satisfied. Nothing surprises you.

👥 The Agents¶

Core Specialists¶

Companion Spirits¶

Quality Validators¶

Each agent is an independent HTTP server communicating via the open A2A (Agent-to-Agent) protocol. They can be deployed separately, tested independently, or swapped for custom implementations.

🔄 How a Request Actually Flows¶

When you ask for something:

sequenceDiagram
    actor You
    participant UI as CLI / GUI / VN
    participant Hephaestus as 🔥 Hephaestus
    participant Specialists as 📐⚙️🧪✨📜<br/>Specialists

    You->>UI: "add user authentication"
    UI->>Hephaestus: A2A stream (SSE)
    Hephaestus->>Hephaestus: LLM selects pipeline

    Hephaestus->>Specialists: Route to Metis (planning)
    Note over Specialists: 📐 Metis analyzes...
    Specialists-->>UI: "JWT or sessions?"
    UI-->>You: Prompt for decision
    You->>UI: "JWT with refresh tokens"

    loop Each specialist in sequence
        Note over Specialists,Hephaestus: Agent streams work<br/>Real-time feedback
        Specialists-->>UI: Status + findings
        UI-->>You: Live updates
    end

    Note over Specialists: If Kallos finds issues → Techne fixes → Kallos re-checks (max 3×)
    Hephaestus-->>UI: Final artifacts + summary
    UI-->>You: Done

Real conversation example:

❯ add authentication to /api/users

🔥 Hephaestus: Analyzing request...
   → Route: Metis → Techne → Dokimasia → Kallos → Mneme

📐 Metis: Spec in progress...
   • Found existing session middleware
   • Should we extend it or use JWT?

❯ JWT with refresh tokens

📐 Metis: Got it. Specification:
   - JWT tokens (15min expiry)
   - Refresh token rotation
   - Rate limiting on token refresh
   ✅ Ready for Techne

⚙️ Techne: Implementing...
   • src/auth/tokens.py — JWT utilities
   • src/api/users.py — Auth middleware
   ✅ Complete

🧪 Dokimasia: Testing... 8 tests, 92% coverage ✅
✨ Kallos: Code review... all clear ✅
🪞 Aidos: Language check... no slop detected ✅

📜 Mneme: Commits ready:
   feat(auth): implement JWT authentication
   - Added JWT token generation and validation
   - Added refresh token rotation
   Files: src/auth/tokens.py, src/api/users.py, tests/...

🎯 Pipelines¶

Hephaestus automatically routes to the right pipeline:

🔄 Human-on-the-Loop (HOTL) Design¶

Instead of silent automation, agents proactively engage when decisions matter:

Ambiguous requirements?

📐 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

Conflicting linting issues?

✨ Kallos: Found 3 issues...
⚙️ Techne: Fixing all 3... ✅
✨ Kallos: Re-checking... All clear!

Nothing gets decided without you. This prevents wasted tokens on speculation and keeps you in control of trade-offs.

💻 Three Ways to Play¶

CLI (Terminal)¶

Fast, scriptable, works anywhere (including SSH). Real-time agent output with emoji progress.

$ kourai "add pagination to /api/items"

🔥 Hephaestus: Routing...
📐 Metis: Spec drafted...
⚙️ Techne: Writing changes...
🧪 Dokimasia: Testing...
✨ Kallos: Reviewing...
📜 Mneme: Commits ready

Pygame GUI (Desktop)¶

Rich visual experience with agent portraits, dialogue bubbles, and personality-matched voices. Each agent has a distinct neural voice and visual appearance.

• 🎨 Full-color agent portraits with glow effects and crossfade transitions
• 💬 Real-time dialogue bubbles with streaming responses
• 🔊 Neural text-to-speech (Kokoro-82M local + Edge-TTS fallback) with real-time streaming
• 🌟 Golden particle system and typewriter effects
• ⚙️ Settings for voice customization and accessibility (WCAG 2.2 AA)

Ren'Py Visual Novel¶

A visual novel where the Golden Maidens aren't just tools — they're characters with personality, affinity, and romance routes.

• 🎭 Warm forge-fire colors and rich portrait aesthetic
• 💛 Affinity system — agents warm up as you work together (4 tiers: Professional → Intimate)
• 💘 Romance routes — confession scenes, jealousy moments, vulnerability
• 🎭 Companion spirits — Puck guides, Cupid coaches romance
• 📖 Gossip system — idle agents share personality-driven flavor text
• 💾 Full save/load with portrait thumbnails and conversation context

All three hosts connect to the same Docker-hosted agent backend. Your choice of experience doesn't change what the agents can do.

🔧 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 — The master craftsman, god of the forge
• Metis — Goddess of wisdom and craft (mother of Athena)
• Techne — Art, craft, and technical skill
• Dokimasia — Scrutiny, examination, proof of competence
• Kallos — Beauty, elegance, aesthetic form
• Mneme — Memory (one of the original three Muses)
• Puck — The mischievous daimon, pragmatic guide
• Cupid — Eros, the force of love and connection
• Aidos — Shame, modesty, the mirror of honesty
• Aletheia — Truth, the unveiling of what is real