Skip to content
Back to search

ralph-tui

AI Agent Loop Orchestrator - A terminal UI for orchestrating AI coding agents to work through task lists autonomously.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/subsy-ralph-tui/badge.svg)](/listings/subsy-ralph-tui)

HTML

<a href="/listings/subsy-ralph-tui"><img src="/api/listings/subsy-ralph-tui/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Install
bun install -g ralph-tui

# Setup your project
cd your-project
ralph-tui setup

# Create a PRD with AI assistance
ralph-tui create-prd --chat

# Run Ralph!
ralph-tui run --prd ./prd.json

That's it! Ralph will work through your tasks autonomously.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 539 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Ralph TUI
  2. [![npm version](https://img.shields.io/npm/v/ralph-tui.svg)](https://www.npmjs.com/package/ralph-tui)
  3. [![CI](https://github.com/subsy/ralph-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/subsy/ralph-tui/actions/workflows/ci.yml)
  4. [![codecov](https://codecov.io/gh/subsy/ralph-tui/graph/badge.svg)](https://codecov.io/gh/subsy/ralph-tui)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  6. [![Built with Bun](https://img.shields.io/badge/Built%20with-Bun-f9f1e1.svg)](https://bun.sh)
  7. **AI Agent Loop Orchestrator** - A terminal UI for orchestrating AI coding agents to work through task lists autonomously.
  8. Ralph TUI connects your AI coding assistant (Claude Code, OpenCode, Factory Droid, Cursor CLI, Gemini CLI, Codex, Kiro CLI, Amp) to your task tracker and runs them in an autonomous loop, completing tasks one-by-one with intelligent selection, error handling, and full visibility.
  9. ![Ralph TUI Screenshot](docs/images/ralph-tui.png)
  10. ## Quick Start
  11. ```bash
  12. # Install
  13. bun install -g ralph-tui
  14. # Setup your project
  15. cd your-project
  16. ralph-tui setup
  17. # Create a PRD with AI assistance
  18. ralph-tui create-prd --chat
  19. # Run Ralph!
  20. ralph-tui run --prd ./prd.json
  21. ```
  22. That's it! Ralph will work through your tasks autonomously.
  23. ## Documentation
  24. **[ralph-tui.com](https://ralph-tui.com)** - Full documentation, guides, and examples.
  25. ### Quick Links
  26. - **[Quick Start Guide](https://ralph-tui.com/docs/getting-started/quick-start)** - Get running in 2 minutes
  27. - **[Installation](https://ralph-tui.com/docs/getting-started/installation)** - All installation options
  28. - **[CLI Reference](https://ralph-tui.com/docs/cli/overview)** - Complete command reference
  29. - **[Configuration](https://ralph-tui.com/docs/configuration/overview)** - Customize Ralph for your workflow
  30. - **[Troubleshooting](https://ralph-tui.com/docs/troubleshooting/common-issues)** - Common issues and solutions
  31. ## How It Works
  32. ```
  33. ┌─────────────────────────────────────────────────────────────────┐
  34. │ │
  35. │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
  36. │ │ 1. SELECT │────▶│ 2. BUILD │────▶│ 3. EXECUTE │ │
  37. │ │ TASK │ │ PROMPT │ │ AGENT │ │
  38. │ └──────────────┘ └──────────────┘ └──────────────┘ │
  39. │ ▲ │ │
  40. │ │ ▼ │
  41. │ ┌──────────────┐ ┌──────────────┐ │
  42. │ │ 5. NEXT │◀────────────────────────│ 4. DETECT │ │
  43. │ │ TASK │ │ COMPLETION │ │
  44. │ └──────────────┘ └──────────────┘ │
  45. │ │
  46. └─────────────────────────────────────────────────────────────────┘
  47. ```
  48. Ralph selects the highest-priority task, builds a prompt, executes your AI agent, detects completion, and repeats until all tasks are done.
  49. ## Features
  50. - **Task Trackers**: prd.json (simple), Beads (git-backed with dependencies)
  51. - **AI Agents**: Claude Code, OpenCode, Factory Droid, Cursor CLI, Gemini CLI, Codex, Kiro CLI, Amp
  52. - **Session Persistence**: Pause anytime, resume later, survive crashes
  53. - **Real-time TUI**: Watch agent output, control execution with keyboard shortcuts
  54. - **Subagent Tracing**: See nested agent calls in real-time
  55. - **Cross-iteration Context**: Automatic progress tracking between tasks
  56. - **Flexible Skills**: Use PRD/task skills directly in your agent or via the TUI
  57. - **Remote Instances**: Monitor and control ralph-tui running on multiple machines from a single TUI
  58. ## CLI Commands
  59. | Command | Description |
  60. |---------|-------------|
  61. | `ralph-tui` | Launch the interactive TUI |
  62. | `ralph-tui run [options]` | Start Ralph execution |
  63. | `ralph-tui resume` | Resume an interrupted session |
  64. | `ralph-tui status` | Check session status |
  65. | `ralph-tui logs` | View iteration output logs |
  66. | `ralph-tui setup` | Run interactive project setup |
  67. | `ralph-tui create-prd` | Create a new PRD interactively |
  68. | `ralph-tui convert` | Convert PRD to tracker format |
  69. | `ralph-tui config show` | Display merged configuration |
  70. | `ralph-tui template show` | Display current prompt template |
  71. | `ralph-tui plugins agents` | List available agent plugins |
  72. | `ralph-tui plugins trackers` | List available tracker plugins |
  73. | `ralph-tui run --listen` | Run with remote listener enabled |
  74. | `ralph-tui remote <cmd>` | Manage remote server connections |
  75. ### Common Options
  76. ```bash
  77. # Run with a PRD file
  78. ralph-tui run --prd ./prd.json
  79. # Run with a Beads epic
  80. ralph-tui run --epic my-epic-id
  81. # Run one parallel session across multiple Beads epics
  82. ralph-tui run --parallel --epic ui-epic --epic backend-epic
  83. ralph-tui run --parallel --epics ui-epic,backend-epic
  84. # Override agent or model
  85. ralph-tui run --agent claude --model sonnet
  86. ralph-tui run --agent opencode --model anthropic/claude-3-5-sonnet
  87. # Limit iterations
  88. ralph-tui run --iterations 5
  89. # Run headless (no TUI)
  90. ralph-tui run --headless
  91. # Reset accumulated progress before starting a new session
  92. ralph-tui run --reset-progress
  93. # Run agent in isolated sandbox (bwrap on Linux, sandbox-exec on macOS)
  94. # Requires bwrap to be installed and on PATH (Linux) or uses built-in sandbox-exec (macOS)
  95. ralph-tui run --sandbox
  96. # Use a bundled color theme by name
  97. ralph-tui run --theme dracula
  98. ```
  99. ### Create PRD Options
  100. ```bash
  101. # Create a PRD with AI assistance (default chat mode)
  102. ralph-tui create-prd
  103. ralph-tui prime # Alias
  104. # Use a custom PRD skill from skills_dir
  105. ralph-tui create-prd --prd-skill my-custom-skill
  106. # Override agent
  107. ralph-tui create-prd --agent claude
  108. # Output to custom directory
  109. ralph-tui create-prd --output ./docs
  110. ```
  111. ### TUI Keyboard Shortcuts
  112. | Key | Action |
  113. |-----|--------|
  114. | `s` | Start execution |
  115. | `p` | Pause/Resume |
  116. | `d` | Toggle dashboard |
  117. | `g` | Cycle scope filter in multi-epic sessions |
  118. | `G` | Reset scope filter to All |
  119. | `T` | Toggle subagent tree panel (Shift+T) |
  120. | `t` | Cycle subagent detail level |
  121. | `o` | Cycle right panel views |
  122. | `a` | Open agent/model picker (local tab only) |
  123. | `,` | Open settings (local tab only) |
  124. | `C` | Open read-only config viewer (Shift+C, works on local and remote tabs) |
  125. | `Alt+C` (Linux) / `Cmd+C` (macOS) / `Ctrl+C` (Windows) | Copy selected text |
  126. | `Ctrl+C` | Interrupt (with confirmation) |
  127. | `q` | Quit |
  128. | `?` | Show help |
  129. | `1-9` | Switch to tab 1-9 (remote instances) |
  130. | `[` / `]` | Previous/Next tab |
  131. | `A` | Add new remote instance |
  132. | `e` | Edit current remote (when viewing remote tab) |
  133. | `x` | Delete current remote (when viewing remote tab) |
  134. **Multi-epic sessions:** Repeated `--epic` and comma-separated `--epics` create one Ralph session across all selected hierarchy-tracker epics. Ralph uses one scheduler, one repo lock, one session branch, one merge queue, and task-scoped worktrees. The TUI scope filter (`g`/`G`) is only a local view filter over that session.
  135. **Dashboard (`d` key):** Toggle a status panel showing:
  136. - Current execution status and active task
  137. - Agent name and model (e.g., `claude-code`, `anthropic/claude-sonnet`)
  138. - Tracker source (e.g., `prd`, `beads`)
  139. - Git branch with dirty indicator (repo:branch*)
  140. - Sandbox status (🔒 enabled, 🔓 disabled) with mode
  141. - Auto-commit setting (✓ auto, ✗ manual)
  142. - Remote connection info (when viewing remote tabs)
  143. See the [full CLI reference](https://ralph-tui.com/docs/cli/overview) for all options.
  144. ### Custom Themes
  145. Ralph TUI supports custom color themes via the `--theme` option:
  146. ```bash
  147. # Use a bundled theme by name
  148. ralph-tui run --theme dracula
  149. # Or use a custom theme file
  150. ralph-tui run --theme ./my-custom-theme.json
  151. ```
  152. ![Custom Theme Example](docs/images/theme-example.png)
  153. Bundled themes: `bright`, `catppuccin`, `dracula`, `high-contrast`, `solarized-light`
  154. See the [Themes documentation](https://ralph-tui.com/docs/configuration/themes) for the full theme schema and creating custom themes.
  155. ### Using Skills Directly in Your Agent
  156. Install ralph-tui skills to your agent using [add-skill](https://github.com/vercel-labs/add-skill):
  157. ```bash
  158. # Install all skills to all detected agents globally
  159. bunx add-skill subsy/ralph-tui --all
  160. # Install to a specific agent
  161. bunx add-skill subsy/ralph-tui -a claude-code -g -y
  162. bunx add-skill subsy/ralph-tui -a kiro-cli -g -y
  163. # Or use the ralph-tui wrapper (maps agent IDs automatically)
  164. ralph-tui skills install
  165. ralph-tui skills install --agent claude
  166. ralph-tui skills install --agent kiro
  167. # If symlinked installs are problematic, copy files instead:
  168. ralph-tui skills install --copy
  169. ```
  170. Use these slash commands in your agent:
  171. ```bash
  172. /ralph-tui-prd # Create a PRD interactively
  173. /ralph-tui-create-json # Convert PRD to prd.json
  174. /ralph-tui-create-beads # Convert PRD to Beads issues
  175. ```
  176. This lets you create PRDs while referencing source files (`@filename`) and using your full conversation context—then use `ralph-tui run` for autonomous execution.
  177. ### Custom Skills Directory
  178. You can configure a custom `skills_dir` in your config file to use custom PRD skills:
  179. ```bash
  180. # In .ralph-tui/config.toml or ~/.config/ralph-tui/config.toml
  181. skills_dir = "/path/to/my-skills"
  182. # Then use custom skills
  183. ralph-tui create-prd --prd-skill my-custom-skill
  184. ```
  185. Skills must be folders inside `skills_dir` containing a `SKILL.md` file.
  186. ## Remote Instance Management
  187. Control multiple ralph-tui instances running on different machines (VPS servers, CI/CD environments, development boxes) from a single TUI.
  188. ```
  189. ┌─────────────────────────────────────────────────────────────────┐
  190. │ LOCAL [1]│ ● prod [2]│ ◐ staging [3]│ ○ dev [4]│ + │
  191. ├─────────────────────────────────────────────────────────────────┤
  192. │ │
  193. │ Your local TUI can connect to and control remote instances │
  194. │ │
  195. └─────────────────────────────────────────────────────────────────┘
  196. ```
  197. ### Quick Start: Remote Control
  198. **On the remote machine (server):**
  199. ```bash
  200. # Start ralph with remote listener enabled
  201. ralph-tui run --listen --prd ./prd.json
  202. # First run generates a secure token - save it!
  203. # ═══════════════════════════════════════════════════════════════
  204. # Remote Listener Enabled
  205. # ═══════════════════════════════════════════════════════════════
  206. # Port: 7890
  207. # New server token generated:
  208. # OGQwNTcxMjM0NTY3ODkwYWJjZGVmMDEyMzQ1Njc4OQ
  209. # ⚠️ Save this token securely - it won't be shown again!
  210. # ═══════════════════════════════════════════════════════════════
  211. ```
  212. **On your local machine (client):**
  213. ```bash
  214. # Add the remote server
  215. ralph-tui remote add prod server.example.com:7890 --token OGQwNTcxMjM0NTY3...
  216. # Test the connection
  217. ralph-tui remote test prod
  218. # Launch TUI - you'll see tabs for local + remote instances
  219. ralph-tui
  220. ```
  221. ### Remote Listener Commands
  222. **Recommended: Use `run --listen`** (runs engine with remote access):
  223. ```bash
  224. # Start with remote listener on default port (7890)
  225. ralph-tui run --listen --prd ./prd.json
  226. # Start with custom port
  227. ralph-tui run --listen --listen-port 8080 --epic my-epic
  228. ```
  229. **Token management:**
  230. ```bash
  231. # Rotate authentication token (invalidates old token immediately)
  232. ralph-tui run --listen --rotate-token --prd ./prd.json
  233. # View remote listener options
  234. ralph-tui run --help
  235. ```
  236. ### Remote Configuration Commands
  237. ```bash
  238. # Add a remote server
  239. ralph-tui remote add <alias> <host:port> --token <token>
  240. # List all remotes with connection status
  241. ralph-tui remote list
  242. # Test connectivity to a specific remote
  243. ralph-tui remote test <alias>
  244. # Remove a remote
  245. ralph-tui remote remove <alias>
  246. # Push config to a remote (propagate your local settings)
  247. ralph-tui remote push-config <alias>
  248. ralph-tui remote push-config --all # Push to all remotes
  249. ```
  250. ### Push Configuration to Remotes
  251. When managing multiple ralph-tui instances, you typically want them all to use the same configuration. The `push-config` command lets you propagate your local config to remote instances:
  252. ```bash
  253. # Push config to a specific remote
  254. ralph-tui remote push-config prod
  255. # Preview what would be pushed (without applying)
  256. ralph-tui remote push-config prod --preview
  257. # Push to all configured remotes
  258. ralph-tui remote push-config --all
  259. # Force overwrite existing config without confirmation
  260. ralph-tui remote push-config prod --force
  261. # Push specific scope (global or project config)
  262. ralph-tui remote push-config prod --scope global
  263. ralph-tui remote push-config prod --scope project
  264. ```
  265. **How it works:**
  266. 1. Reads your local config (`~/.config/ralph-tui/config.toml` or `.ralph-tui/config.toml`)
  267. 2. Connects to the remote instance
  268. 3. Checks what config exists on the remote
  269. 4. Creates a backup if overwriting (e.g., `config.toml.backup.2026-01-19T12-30-00-000Z`)
  270. 5. Writes the new config
  271. 6. Triggers auto-migration to install skills/templates
  272. **Scope selection:**
  273. - `--scope global`: Push to `~/.config/ralph-tui/config.toml` on remote
  274. - `--scope project`: Push to `.ralph-tui/config.toml` in remote's working directory
  275. - Without `--scope`: Auto-detects based on what exists locally and remotely
  276. ### Security Model
  277. Ralph uses a two-tier token system for secure remote access:
  278. | Token Type | Lifetime | Purpose |
  279. |------------|----------|---------|
  280. | Server Token | 90 days | Initial authentication, stored on disk |
  281. | Connection Token | 24 hours | Session authentication, auto-refreshed |
  282. **Security features:**
  283. - Without a token configured, the listener binds only to localhost (127.0.0.1)
  284. - With a token configured, the listener binds to all interfaces (0.0.0.0)
  285. - All connections require authentication
  286. - All remote actions are logged to `~/.config/ralph-tui/audit.log`
  287. - Tokens are shown only once at generation time
  288. ### Connection Resilience
  289. Remote connections automatically handle network interruptions:
  290. - **Auto-reconnect**: Exponential backoff from 1s to 30s (max 10 retries)
  291. - **Silent retries**: First 3 retries are silent, then toast notifications appear
  292. - **Status indicators**: `●` connected, `◐` connecting, `⟳` reconnecting, `○` disconnected
  293. - **Metrics display**: Latency (ms) and connection duration shown in tab bar
  294. ### Tab Navigation
  295. When connected to remote instances, a tab bar appears at the top of the TUI:
  296. | Key | Action |
  297. |-----|--------|
  298. | `1-9` | Jump directly to tab 1-9 |
  299. | `[` | Previous tab |
  300. | `]` | Next tab |
  301. | `Ctrl+Tab` | Next tab |
  302. | `Ctrl+Shift+Tab` | Previous tab |
  303. The first tab is always "Local" (your current machine). Remote tabs show the alias you configured with connection status.
  304. ### Managing Remotes from the TUI
  305. You can add, edit, and delete remote servers directly from the TUI without leaving the interface:
  306. **Add Remote (`A` key):**
  307. Opens a form dialog to configure a new remote:
  308. - **Alias**: A short name for the remote (e.g., "prod", "dev-server")
  309. - **Host**: The server address (e.g., "192.168.1.100", "server.example.com")
  310. - **Port**: The listener port (default: 7890)
  311. - **Token**: The server token (displayed on the remote when you start with `--listen`)
  312. Use `Tab`/`Shift+Tab` to move between fields, `Enter` to save, `Esc` to cancel.
  313. **Edit Remote (`e` key):**
  314. When viewing a remote tab, press `e` to edit its configuration. The form pre-fills with current values. You can change any field, including the alias.
  315. **Delete Remote (`x` key):**
  316. When viewing a remote tab, press `x` to delete it. A confirmation dialog shows the remote details before deletion.
  317. ### Full Remote Control
  318. When connected to a remote instance, you have full control:
  319. - **View**: Agent output, logs, progress, task list
  320. - **Control**: Pause, resume, cancel execution
  321. - **Modify**: Add/remove iterations, refresh tasks
  322. - **Start**: Begin new task execution
  323. All operations work identically to local control with <100ms perceived latency.
  324. ### Configuration Files
  325. | File | Purpose |
  326. |------|---------|
  327. | `~/.config/ralph-tui/remote.json` | Server token storage |
  328. | `~/.config/ralph-tui/remotes.toml` | Remote server configurations |
  329. | `~/.config/ralph-tui/audit.log` | Audit log of all remote actions |
  330. | `~/.config/ralph-tui/listen.pid` | Daemon PID file |
  331. ## Contributing
  332. ### Development Setup
  333. ```bash
  334. git clone https://github.com/subsy/ralph-tui.git
  335. cd ralph-tui
  336. bun install
  337. bun run dev
  338. ```
  339. ### Build & Test
  340. ```bash
  341. bun run build # Build the project
  342. bun run typecheck # Type check (no emit)
  343. bun run lint # Run linter
  344. bun run lint:fix # Auto-fix lint issues
  345. ```
  346. ### Testing
  347. ```bash
  348. bun test # Run all tests
  349. bun test --watch # Run tests in watch mode
  350. bun test --coverage # Run tests with coverage
  351. ```
  352. See [CONTRIBUTING.md](CONTRIBUTING.md#testing) for detailed testing documentation including:
  353. - Test file naming conventions
  354. - Using factories and mocks
  355. - Writing new tests
  356. - Coverage requirements
  357. ### Pull Request Requirements
  358. PRs must meet these requirements before being merged:
  359. - **>50% test coverage** on new/changed lines (enforced by Codecov)
  360. - **Documentation updates** for any new or changed features
  361. - All CI checks passing (typecheck, lint, tests)
  362. See [CONTRIBUTING.md](CONTRIBUTING.md#pull-request-guidelines) for full PR guidelines.
  363. ### Project Structure
  364. ```
  365. ralph-tui/
  366. ├── src/
  367. │ ├── cli.tsx # CLI entry point
  368. │ ├── commands/ # CLI commands (run, resume, status, logs, listen, remote, etc.)
  369. │ ├── config/ # Configuration loading and validation (Zod schemas)
  370. │ ├── engine/ # Execution engine (iteration loop, events)
  371. │ ├── interruption/ # Signal handling and graceful shutdown
  372. │ ├── logs/ # Iteration log persistence
  373. │ ├── plugins/
  374. │ │ ├── agents/ # Agent plugins (claude, opencode)
  375. │ │ │ └── tracing/ # Subagent tracing parser
  376. │ │ └── trackers/ # Tracker plugins (beads, beads-bv, json)
  377. │ ├── remote/ # Remote instance management
  378. │ │ ├── server.ts # WebSocket server for remote control
  379. │ │ ├── client.ts # WebSocket client with auto-reconnect
  380. │ │ ├── token.ts # Two-tier token management
  381. │ │ ├── config.ts # Remote server configuration (TOML)
  382. │ │ ├── audit.ts # JSONL audit logging
  383. │ │ └── types.ts # Type definitions
  384. │ ├── session/ # Session persistence and lock management
  385. │ ├── setup/ # Interactive setup wizard
  386. │ ├── templates/ # Handlebars prompt templates
  387. │ ├── chat/ # AI chat mode for PRD creation
  388. │ ├── prd/ # PRD generation and parsing
  389. │ └── tui/ # Terminal UI components (OpenTUI/React)
  390. │ └── components/ # React components (TabBar, Toast, etc.)
  391. ├── skills/ # Bundled skills for PRD/task creation
  392. │ ├── ralph-tui-prd/
  393. │ ├── ralph-tui-create-json/
  394. │ └── ralph-tui-create-beads/
  395. ├── website/ # Documentation website (Next.js)
  396. └── docs/ # Images and static assets
  397. ```
  398. ### Key Technologies
  399. - [Bun](https://bun.sh) - JavaScript runtime
  400. - [OpenTUI](https://github.com/sst/opentui) - Terminal UI framework
  401. - [Handlebars](https://handlebarsjs.com) - Prompt templating
  402. See [CLAUDE.md](CLAUDE.md) for detailed development guidelines.
  403. ## Credits
  404. Thanks to Geoffrey Huntley for the [original Ralph Wiggum loop concept](https://ghuntley.com/ralph/).
  405. ## License
  406. MIT License - see [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.