Ralph TUI CLI
A terminal dashboard that drives Claude Code, Codex and five more agents through a task list in a loop until the list is done
- 2,461 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Runs coding agents in an autonomous loop: they edit files and run commands in the project without confirming each iteration
- May commit on its own when auto-commit is on, and creates worktrees and session branches
- Spends tokens and money on the connected agent's plan while the loop runs
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/ralph-tuiDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Runs coding agents in an autonomous loop: they edit files and run commands in the project without confirming each iteration
- May commit on its own when auto-commit is on, and creates worktrees and session branches
- Spends tokens and money on the connected agent's plan while the loop runs
This is third-party code. Review the repository files before installing.
What it does
Ralph TUI runs an AI agent in a loop over a task list and shows progress in a terminal interface. On each iteration it picks the highest-priority task, builds a prompt, runs the agent, detects completion and moves on. It supports Claude Code, OpenCode, Factory Droid, Cursor CLI, Gemini CLI, Codex and Kiro CLI, and takes tasks from a prd.json file or from the Beads tracker with dependencies. Installation goes through Bun: `bun install -g ralph-tui`. Then `ralph-tui setup` configures the project, `ralph-tui create-prd --chat` helps draft a PRD with the agent, and `ralph-tui run --prd ./prd.json` starts the loop. Flags set the agent and model (`--agent claude --model sonnet`), the iteration count, headless mode with `--headless` and a sandbox with `--sandbox` on bwrap in Linux or sandbox-exec in macOS. A session can be paused and resumed, it survives crashes, and `ralph-tui resume` brings back an interrupted run. The panel shows agent output, the tree of nested agents, the git branch, the auto-commit setting and sandbox state. Parallel mode runs several Beads epics in one session with a shared branch, a merge queue and a worktree per task. The skills ralph-tui-prd, ralph-tui-create-json and ralph-tui-create-beads are also usable directly inside an agent, and `ralph-tui skills install` installs them.
Who it is for. Developers who hand Claude Code or Codex a whole task list overnight and want to watch progress, pause and come back to the session.
Good fit when
- The PRD is ready and holds ten tasks: `ralph-tui run --prd ./prd.json` goes through them by priority until the list is empty
- Two Beads epics run in parallel: `--parallel --epic ui-epic --epic backend-epic` keeps one session with a worktree per task
- The agent crashed mid-run: the session is saved, and `ralph-tui resume` continues from where it stopped
- You want to watch the work: the panel shows agent output, the nested agent tree and git state
- Agents run on several machines: remote instances gather into tabs of one terminal
Not a fit when
- You need one short edit: a PRD-and-tracker loop is overkill for that
- Tasks are written neither in prd.json nor in Beads: Ralph walks a ready list and does not invent work
- bwrap is not installed on Linux: the `--sandbox` sandbox will not start without it
- You need the agent in a live dialogue: Ralph runs it one task per iteration
Example request
Draft a PRD for the profile settings page, turn it into prd.json and run `ralph-tui run --prd ./prd.json --iterations 5` with the claude agentLimitations
- It installs through Bun. Seven agents from the README list and two trackers are supported: the prd.json file and Beads.
- The `--sandbox` mode needs bwrap installed on Linux, and uses the built-in sandbox-exec on macOS.
- The auto-commit setting shows in the panel: decide in advance whether the agent commits on its own.
- Parallel mode runs the epics of one session with one scheduler and a repository lock.
- Configuration lives in `.ralph-tui/config.toml` in the project or `~/.config/ralph-tui/config.toml`, and custom PRD skills are connected with the `skills_dir` setting.
How to disable. Remove the tool with `bun remove -g ralph-tui`. Skills installed by `ralph-tui skills install` sit in the agent's skills directory: delete the folders starting with ralph-tui- from there.
FAQ
How do I run Ralph TUI with Claude Code?
Install the tool with `bun install -g ralph-tui`, run `ralph-tui setup` in the project and start `ralph-tui run --prd ./prd.json --agent claude`. Get prd.json from a PRD with `ralph-tui convert` or the ralph-tui-create-json skill.
How is Ralph TUI different from ralph-orchestrator and ralphy?
Ralph TUI builds a terminal dashboard around the loop: agent output, pause, session resume and tabs for remote machines. It takes tasks from a PRD or Beads by priority.
Which task trackers are supported?
Two: a plain prd.json file and Beads, a git-backed tracker with task dependencies. Parallel mode works on Beads epic hierarchies.
Is it safe to run Ralph unattended?
The `--sandbox` flag isolates the agent with bwrap on Linux or sandbox-exec on macOS, and `--iterations` caps the number of iterations. Without the sandbox the agent works with your user's permissions, as in a normal run.
Which agents does Ralph TUI support?
Claude Code, OpenCode, Factory Droid, Cursor CLI, Gemini CLI, Codex and Kiro CLI. The agent and model are chosen with the `--agent` and `--model` flags or with the `a` key in the dashboard.
Discussion
No questions or reviews yet.
Related
CLI toolsA Ralph loop for long tasks: an agent in a Docker sandbox works through a PRD task list, checks each task with tests and commits until the list is done
The ralph command repeats one prompt for Claude Code, Codex, Cursor Agent or OpenCode until a completion tag appears in the reply
A CLI orchestrator that loops Claude Code, Codex, Gemini CLI and other agents until a task is done and blocks incomplete work with tests and lint
A CLI that installs BMAD planning and the Ralph loop: BMAD roles write the PRD and stories, then an agent builds them test-first
An autonomous spec-driven coding loop: the agent takes a task, checks acceptance criteria and commits until the list runs out.
Autonomous plan execution task by task: each task in a fresh Claude Code or Codex session, then a multi-pass review. Written in Go
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Ralph TUI (this card) | no | 2,461 | ||
| Ralph Orchestrator | no | not required | 3,194 | an orchestrator that blocks incomplete work with tests and a linter; Ralph TUI focuses on the dashboard and sessions |
| Ralphy | no | 2,982 | runs agents through a task list or PRD; Ralph TUI adds a dashboard with pause, resume and remote machine tabs | |
| Open Ralph Wiggum | no | 1,908 | repeats one prompt until a completion marker, while Ralph TUI takes tasks in turn from a PRD or Beads |
README in short
The README opens with a four-command quick start and links to the docs at ralph-tui.com. Next come a five-step loop diagram, the feature list, a command table, the dashboard's keyboard shortcuts, theme options and a section on managing remote instances. Bun development commands and the MIT license close the page.