# Kourai Khryseai > 10 A2A-protocol agents that plan, code, test, review, and ship β€” through a CLI, Pygame GUI, or Ren'Py visual novel. - **Type:** MCP server - **Install:** `agentstack add mcp-ajbarea-kourai-khryseai` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [ajbarea](https://agentstack.voostack.com/s/ajbarea) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [ajbarea](https://github.com/ajbarea) - **Source:** https://github.com/ajbarea/kourai-khryseai - **Website:** https://ajbarea.github.io/kourai-khryseai/ ## Install ```sh agentstack add mcp-ajbarea-kourai-khryseai ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # πŸ›οΈ Κοῦραι ΧρύσΡαι ### **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.* [](https://a2a-protocol.org) [](https://python.org) [](https://docs.astral.sh/uv/) [](https://codecov.io/gh/ajbarea/kourai-khryseai) [](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** | 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](https://a2a-protocol.org). They can be deployed separately, tested independently, or swapped for custom implementations. --- ## How It Works ### 1. You Start a Conversation **CLI (interactive REPL):** ```bash $ uv run kourai-dev cli ❯ implement CSV export with tests ``` **Or GUI (visual interface):** ```bash $ uv run kourai-dev gui ``` **Or VN (Ren'Py visual novel):** ```bash $ 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 ` below has a `make ` shorthand if you prefer β€” the Makefile is a thin compatibility wrapper around the same dev CLI. ### 1. Install ```bash 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)?** ```bash # Install Ollama, pull models, then: KOURAI_PROVIDER=local uv run kourai-dev cli ``` ### 2. Start the Agents ```bash 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:** ```bash uv run kourai-dev cli ❯ implement CSV export with tests ``` **GUI (richer experience with voices and visuals):** ```bash uv run kourai-dev gui ``` **VN (Ren'Py visual novel with affinity, romance routes, save/load):** ```bash uv run kourai-dev vn # see hosts/vn/README.md for Ren'Py SDK resolution ``` See [Getting Started](docs/getting-started.md) 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. ```bash 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 # or /project discard ``` Projects live under `~/.kourai_khryseai/projects//`. Templates: `empty`, `python`, `node`, `backend`, `frontend`. **Sandboxed execution (opt-in):** route every agent-issued command through a locked-down container. ```bash 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. ```bash ❯ 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](./ROADMAP.md#m20--audio-text-synchronization-across-cli--gui--vn)) - βš™οΈ 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](docs/vn.md) for architecture and [`hosts/vn/README.md`](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: ```bash # .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](docs/configuration.md#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](https://huggingface.co/hexgrad/Kokoro-82M)). - **Edge-TTS (Fallback)**: Microsoft Azure Neural voices (requires internet). See [Configuration](docs/configuration.md) for full environment variable reference. --- ## Development ```bash 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: ```bash 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](docs/theoros.md) for the role split, the prompt library, and troubleshooting. **Stack:** - **Framework** β€” [a2a-sdk](https://github.com/a2a-org/a2a-sdk) + [Starlette](https://www.starlette.io/) - **Language** β€” Python 3.12+ with modern type hints - **LLM** β€” [LiteLLM](https://docs.litellm.ai/) (pluggable: Claude, Gemini, Ollama, etc.) - **TTS** β€” **Kokoro-82M** (Local) / **Edge-TTS** (Cloud) with real-time streaming - **MCP** β€” [MCP](https://modelcontextprotocol.io/) (filesystem, git, shell, context7) - **Linting** β€” [Ruff](https://docs.astral.sh/ruff/) + [ty](https://docs.astral.sh/ty/) (Python) - **Packaging** β€” [uv](https://docs.astral.sh/uv/) workspaces - **Observability** β€” [OpenTelemetry](https://opentelemetry.io/) β†’ [Jaeger](https://www.jaegertracing.io/) + [Prometheus](https://prometheus.io/) - **Containers** β€” Docker + Docker Compose - **Docs** β€” [Zensical](https://zensical.dev) --- ## 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`](http://localhost:16686)) β€” traces: A2A hops, MCP tool calls, full pipeline timing. RED metrics (Rate, Error, Duration) via the spanmetrics connector. - **Prometheus** ([`localhost:9090`](http://localhost:9090)) β€” metrics: latency percentiles, rates, error counts. - **Dozzle** ([`localhost:8888`](http://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](docs/observability.md) for the cross-tool linking pattern and triage runbook. --- ## Trust + security Kourai sits in the same conceptual neighborhood as [Anthropic's Project Glasswing](https://www.anthropic.com/glasswing) (April 2026): t … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [ajbarea](https://github.com/ajbarea) - **Source:** [ajbarea/kourai-khryseai](https://github.com/ajbarea/kourai-khryseai) - **License:** MIT - **Homepage:** https://ajbarea.github.io/kourai-khryseai/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-ajbarea-kourai-khryseai - Seller: https://agentstack.voostack.com/s/ajbarea - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.