KuroryuuKuroryuu
Back to Blog
2026-02-10|Ryan

Inside the Architecture: How Kuroryuu Works

architecturetechnicalclaude-code

The Stack

Kuroryuu is four systems working together:

| Layer | Technology | Role | |-------|-----------|------| | Gateway | Python FastAPI | API bridge, MCP server, tool orchestration | | Desktop | Electron + React + TypeScript | Visual UI, agent monitoring, team management | | MCP Tools | 15 tools, 107 actions | Agent capabilities (RAG, checkpoints, PTY, memory) | | CLI | Python REPL (6,137 LOC) | 24 commands, 3 LLM providers, slash command system |

Gateway

The Gateway is the nerve center. A FastAPI server on port 8200 with 21 routers exposing everything agents need:

  • MCP endpoint (/v1/mcp/call) — JSON-RPC 2.0 compliant tool routing
  • Streaming chat — SSE-based responses from multiple LLM backends
  • Traffic monitoring — Real-time WebSocket events for every request
  • Security — Auto-detect and block external connections, threat intelligence via ip-api.com
  • Health checks — /v1/health for service monitoring

The Gateway supports three LLM providers: Claude API, LM Studio (local inference), and CLIProxyAPI (multi-provider routing to 61+ models).

Desktop Application

235 React components across 16 screens and 13 modals. Built with Electron + Vite for fast iteration.

Key screens:

  • Agent Graph — ReactFlow visualization with 3 views: Hub+Spokes, Hierarchy, and Timeline
  • Kanban Board — Task management synced to the filesystem (~/.claude/tasks/)
  • Terminal Grid — Multi-terminal layout with PTY integration
  • Memory Panel — Visualize and edit Claude's project memory with CodeMirror 6
  • Traffic Monitor — Real-time API traffic with network graph visualization
  • GenUI Dashboard — Generate UI dashboards from markdown (51 component types)

Four visual themes: Default, Cyberpunk, Kuroryuu (imperial Japanese), and Retro — all driven by CSS variables. The theme system replaced 1,165 hardcoded color values.

Multi-Agent Orchestration

The core of Kuroryuu. How multiple AI agents coordinate:

Leader/Worker Pattern — A leader agent delegates tasks to workers. Each worker runs in its own terminal with its own PTY session. The leader monitors progress via heartbeat, reassigns on failure, and aggregates results.

PTY Inter-Agent Control — This is the unique piece. Kuroryuu can read from and write to agent terminal sessions. A leader can inspect what a worker is doing, nudge it with targeted writes, or detect when it's stuck. No other orchestration platform has this.

Evidence Chains — Every piece of work is linked:

Plan → Checkpoint → Worklog → Task

Plans reference checkpoints. Checkpoints reference worklogs. Worklogs reference tasks. Nothing gets lost.

Agent Registry — Heartbeat monitoring with configurable thresholds. Health dots on graph nodes show agent status in real-time. Unresponsive detection triggers after 5 minutes.

The Competition

We ran 15 parallel analysis agents against every major competitor:

| Project | GitHub Stars | What They Have | What Kuroryuu Adds | |---------|-------------|----------------|-------------------| | OpenHands | 67K | Event sourcing | PTY control, Desktop UI | | MetaGPT | 63K | Pub/sub agents | Persistence, evidence chains | | AutoGen | 54K | Typed messages | MCP gateway, local LLM support | | CrewAI | 43K | Role personas | Full checkpoint/resume | | Aider | 40K | Git-native editing | Multi-agent orchestration |

Kuroryuu's unique advantages:

  • PTY inter-agent control (no competitor has this)
  • Desktop UI with Gantt charts and graph visualization
  • MCP gateway architecture
  • Evidence chains (plan ↔ checkpoint ↔ worklog)
  • TOS compliant (CLI subprocess, not OAuth extraction)

Getting Started

Clone the repo and you're running in minutes. See the installation guide or read about the hackathon sprint that built it all.