How subsy/ralph-tui works
Project Type & Purpose
• Ralph TUI is a monorepo containing two main “applications”:
a) A CLI-driven AI Agent Loop Orchestrator (terminal TUI) that selects tasks, builds prompts, executes agents, detects completion, persists state, and supports remote control.
b) A static documentation website (Next.js) for docs and marketing.
High-Level File Structure & Patterns
• Top-level directories:
• src/ – core of the CLI tool, subdivided by feature area (cli, commands, config, engine, plugins, remote, session, setup, prd, chat, tui, parallel, sandbox, logs, interruption, templates).
• website/ – Next.js app for docs.
• docs/, assets/ – static docs and theme/sound assets.
• skills/ – bundled AI-agent “skills” (Markdown-based).
• Patterns:
• Plugin architecture under src/plugins (agents & trackers).
• Event-driven engine loop under src/engine.
• Layer separation: CLI entry → command handlers → core engine → persistence & plugins → TUI/rendering or remote API.
• Remote control via WebSocket server/client under src/remote.
Key Architectural Components
a. CLI & Command Layer
• Entry point: src/index.ts / src/cli.tsx
• Command modules: src/commands/* parse flags, invoke core services (run, resume, status, setup, create-prd, remote, etc.).
b. Configuration Layer
• src/config: loads & validates user config (Zod schemas), merges defaults/global/project settings.
c. Core Engine Loop
• src/engine: implements the 5-step loop (select→build→execute→detect→next), emits events.
• Parallel execution: src/parallel (task graph, worker, conflict resolution).
• Interruption & signal handling: src/interruption.
d. Plugin Subsystems
• Agents: src/plugins/agents/* – adapters for Claude, Codex, Droid, Gemini, Kiro.
• Trackers: src/plugins/trackers/* – PRD, Beads, JSON trackers with Handlebars templates.
• Registry & dynamic loading.
e. Session & Logging
• Session persistence & locks: src/session.
• Logs & structured logger: src/logs.
f. TUI Layer
• src/tui – React/OpenTUI components render the dashboard, chat view, remote tabs, themes, keyboard handlers.
g. Remote Control
• WebSocket server (src/remote/server.ts) embedded in “run --listen”.
• WebSocket client (src/remote/client.ts) in the local TUI to control remote instances.
• Token management & audit logging.
h. Support Systems
• PRD creation & chat: src/chat, src/prd, src/templates (Handlebars).
• Sandbox wrapper: src/sandbox.
• Utilities: src/utils, testing harness, schema definitions.
i. Docs Website
• website/: Next.js app sourcing markdown .mdx under website/content and using website/lib utilities.
Interactions & Data Flow
• CLI entry → Command Handler → Config Loader → Core Engine
• Engine ↔ Plugins: for each iteration, engine calls Tracker (to fetch next task) and Agent (to execute prompt).
• Engine emits events → Session & Logs store progress.
• TUI subscribes to engine events (in‐process) to render real-time dashboard.
• “run --listen” → Engine also instantiates WebSocket server → Remote clients connect → send control commands & receive events.
• PRD generation path: CLI “create-prd” invokes chat + prd modules → outputs JSON/Beads.
• Parallel mode: engine delegates to parallel executor → fork workers (sandboxed) → merge results.
• Website is entirely decoupled: built from markdown, deployed separately.