Project context file for AI agents (Claude Code, Cursor, etc.). Drop this into your repo root as AGENTS.md or feed it as context so the agent understands what Ryu is, how it's structured, and how to work on it.
Ryu is a local-first AI assistant platform built in Rust. It wraps ZeroClaw (an open-source autonomous agent runtime) as a managed binary sidecar and extends it with a desktop app, visual workflows, document Spaces, cloud model routing, and custom MCP tool servers.
Core idea: ZeroClaw handles agents, memory, RAG, 16+ messaging channels, and security (all deny-by-default, all config-driven). Ryu handles the product layer: UI, workflows, Spaces, cloud, and developer experience. We don't build the agent layer, the security layer, or the messaging layer, we just configure them.
Interfaces (thin clients)
Desktop (Tauri V2) / CLI / 16+ Channels
│ HTTP / WebSocket
▼
Ryu Core (Rust binary, port 3117)
API server, sidecar management, Spaces, workflow bridge,
cloud routing, config management
│
▼
ZeroClaw (agent core, managed binary sidecar)
Agents, sub-agents, memory (SQLite + vector), RAG,
encryption, channels, MCP client, providers, security
│
▼
Sidecars (optional local processes)
Temporal (workflow engine) / Ollama (local inference)
│
▼
MCP Servers (tool integrations)
Screenpipe / Spider / Ryu tools / user-installed servers
│ (optional)
▼
Ryu Cloud (PaaS)
OpenRouter proxy (300+ models), Composio OAuth,
usage tracking, billing
ryu/
├── ryu-core/ # Main Rust binary
│ └── src/
│ ├── main.rs # Entry point: tokio runtime, tracing, axum server
│ ├── config/
│ │ └── mod.rs # Unified config.toml parser + file watcher
│ ├── server/
│ │ ├── mod.rs # axum router setup
│ │ ├── ws.rs # WebSocket endpoints (/ws/chat, /ws/events)
│ │ └── routes/
│ │ ├── chat.rs # Chat + request routing to ZeroClaw
│ │ ├── agents.rs # Agent config API (thin proxy to ZeroClaw)
│ │ ├── spaces.rs # Spaces CRUD + document upload
│ │ ├── workflows.rs # Workflow execution + status
│ │ ├── models.rs # Local model management (Ollama)
│ │ ├── settings.rs # Config read/write API
│ │ └── approvals.rs # Human approval gate API
│ ├── sidecar/
│ │ ├── mod.rs # Sidecar trait + SidecarManager
│ │ ├── download_manager.rs # Generic binary downloader
│ │ ├── manager.rs # Lifecycle: start/stop/restart with ordering
│ │ ├── zeroclaw/
│ │ │ ├── downloader.rs # ZeroClaw binary download + checksum
│ │ │ ├── config_gen.rs # Generate ZeroClaw config.toml from Ryu settings
│ │ │ ├── process.rs # Spawn/stop ZeroClaw subprocess
│ │ │ ├── health.rs # Health check + auto-restart
│ │ │ ├── client.rs # HTTP/SSE client for ZeroClaw API
│ │ │ ├── shutdown.rs # Graceful shutdown sequence
│ │ │ ├── updater.rs # Binary update mechanism
│ │ │ ├── mcp_registry.rs # Register MCP servers in ZeroClaw config
│ │ │ ├── providers.rs # Provider config (Cloud/BYOK/BYOS/Local)
│ │ │ ├── channels.rs # 16+ messaging channel config (all ZeroClaw-native)
│ │ │ └── skills.rs # Ryu skills directory setup
│ │ ├── temporal/
│ │ │ ├── mod.rs # Temporal sidecar (download, spawn, health)
│ │ │ └── process.rs # Temporal process management
│ │ └── llamacpp/
│ │ ├── mod.rs # Ollama sidecar management
│ │ └── process.rs # Ollama process management
│ ├── spaces/
│ │ ├── mod.rs # Spaces feature module
│ │ ├── manager.rs # CRUD operations (SQLite at ~/.ryu/spaces.db)
│ │ ├── indexer.rs # Document chunking + embedding via ZeroClaw
│ │ └── search.rs # Scoped vector search within a Space
│ ├── workflows/
│ │ ├── temporal_client.rs # Temporal Rust SDK client
│ │ ├── worker.rs # Temporal worker registration
│ │ ├── bridge.rs # DAG JSON to Temporal workflow converter
│ │ ├── dag.rs # DAG parsing + topological sort
│ │ ├── retry.rs # Retry policies per activity type
│ │ ├── status.rs # Workflow status querying
│ │ └── types/
│ │ ├── sequential.rs # Sequential chain workflow
│ │ ├── parallel.rs # Fan-out/fan-in workflow
│ │ └── approval_gate.rs # Human approval step
│ ├── cloud/
│ │ ├── router.rs # Cloud routing + JWT auth
│ │ ├── auth.rs # Token management + refresh
│ │ └── byok.rs # BYOK/BYOS provider logic
│ ├── mcp/
│ │ ├── registry.rs # Config-driven MCP server management
│ │ ├── discovery.rs # Validate + merge user MCP servers into ZeroClaw config
│ │ ├── health.rs # MCP server health monitoring
│ │ ├── screenpipe/ # Screenpipe sidecar download + config registration
│ │ ├── spider/ # Spider web crawling MCP server
│ │ │ ├── mod.rs
│ │ │ ├── server.rs # MCP server setup (stdio transport)
│ │ │ └── tools.rs # crawl_page, crawl_site, extract, screenshot
│ │ └── ryu_tools/ # Ryu-specific MCP tools (Spaces, workflows)
│ │ ├── mod.rs
│ │ └── server.rs # HTTP transport MCP server
│ ├── routing/
│ │ └── mod.rs # Request routing: interface -> agent
│ └── security/ # Config-gen only, ZeroClaw enforces all security
│ ├── workspace.rs # Workspace isolation config gen
│ ├── permissions.rs # Sub-agent permission scoping config gen
│ ├── allowlists.rs # Tool allowlists + channel auth config gen
│ ├── credentials.rs # Credential injection (OS keychain, Ryu-specific)
│ └── encryption.rs # AES-GCM encrypted local storage
│
├── ryu-desktop/ # Tauri V2 desktop app
│ ├── src-tauri/
│ │ └── src/
│ │ └── commands.rs # Tauri IPC commands (start/stop Ryu Core)
│ └── src/
│ ├── views/
│ │ ├── Chat.tsx # Chat UI with streaming
│ │ ├── Agents.tsx # Agent config management (proxied to ZeroClaw)
│ │ ├── Spaces.tsx # Document collections + search
│ │ ├── Workflows.tsx # Visual workflow builder (React Flow)
│ │ └── Settings.tsx # Provider keys, sidecars, MCP, security
│ ├── components/
│ │ ├── ChatMessage.tsx
│ │ ├── ChatInput.tsx
│ │ ├── AgentCard.tsx
│ │ ├── AgentEditor.tsx
│ │ ├── SpaceCard.tsx
│ │ ├── DocumentList.tsx
│ │ ├── SearchPanel.tsx
│ │ ├── NotificationCenter.tsx
│ │ ├── workflow/
│ │ │ ├── Canvas.tsx # React Flow canvas
│ │ │ ├── NodeEditor.tsx
│ │ │ └── nodes/ # Trigger, LLM, Search, Crawl, Transform, etc.
│ │ └── settings/ # Settings section components
│ └── hooks/
│ ├── useChat.ts # WebSocket chat hook
│ └── useNotifications.ts
│
├── cli/ # CLI binary
│ └── src/
│ └── commands/
│ ├── chat.rs # ryu chat (interactive REPL)
│ ├── agents.rs # ryu agents (config CRUD, proxied to ZeroClaw)
│ ├── spaces.rs # ryu spaces (CRUD + search)
│ ├── workflows.rs # ryu workflows (run, status, approve)
│ ├── mcp.rs # ryu mcp (server management)
│ └── config.rs # ryu config (view/edit)
│
├── cloud/ # Ryu Cloud (deployed service)
│ └── src/
│ ├── routes/
│ │ ├── openrouter.rs # OpenRouter proxy endpoint
│ │ └── integrations.rs # Composio OAuth flow
│ ├── proxy.rs # Request forwarding + header injection
│ ├── usage/
│ │ ├── mod.rs # Usage event logging
│ │ └── caps.rs # Per-agent spending caps
│ └── billing/
│ └── mod.rs # Stripe integration
│
├── Cargo.toml # Workspace root
└── config.toml.example # Example config
[dependencies]
tokio = { version = "1", features = ["full"] }
axum = { version = "0.7", features = ["ws"] }
tower = "0.4"
tower-http = { version = "0.5", features = ["cors", "trace"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
toml = "0.8"
reqwest = { version = "0.12", features = ["json", "stream"] }
dirs = "5"
rusqlite = { version = "0.31", features = ["bundled"] }
uuid = { version = "1", features = ["v4"] }
semver = "1"
sha2 = "0.10"
notify = "6" # File watcher for config
keyring = "2" # OS keychain for credentials
aes-gcm = "0.10" # Encrypted local storage
argon2 = "0.5" # Key derivation
temporal-sdk = "*" # Temporal Rust SDK
mcp-server = "*" # MCP server SDK
Desktop app: