Ralphy 🌙

Your coding agents, your repos, your machine — in a browser tab you can open from anywhere.

Ralphy is one small binary that turns the computer where your code lives into a workspace you can reach from any other screen. It runs a resident daemon on your box and serves a workbench: projects, a file explorer with a real editor, your git changes, your issue board, live runs, spend — and real agent terminals (Claude, Codex, OpenCode, Copilot, Cursor, Gemini, Kimi) side by side in one tab.

The terminals belong to the daemon, not to the browser. Close the laptop, pick up the tablet, open the same URL: the sessions are still running, with their scrollback, and your window layout comes back with them.

And when you're done for the day, the same binary can work your backlog while you sleep.

     🏠 your machine                      🌍 any screen you happen to have
┌───────────────────────────┐          ┌──────────┐ ┌──────────┐ ┌──────────┐
│  ralphy daemon            │          │ desktop  │ │ notebook │ │  tablet  │
│  · your repos             │  ◀────▶  │          │ │          │ │  / phone │
│  · your agent sessions    │          └──────────┘ └──────────┘ └──────────┘
│  · your gh login          │             one workbench, same sessions,
└───────────────────────────┘                 same layout, no upload

Three things worth knowing up front:

• 🔒 No cloud of ours. The daemon runs on your box, binds to loopback by default, and reads the same repos and the same gh login you already use. Your code goes only to the agent you chose, and issue data only to GitHub.
• 💳 No API key, no per-token bill. Ralphy drives the agent CLIs you're already signed into, on the subscription you already pay for.
• 💻 Windows, Linux, and macOS, one binary, no runtime to install.

---

🚀 Get it running

📦 1 — Get the ralphy binary

One line installs it for your user. On Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/paulocorcino/ralphy/main/assets/install/install.sh | sh

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/paulocorcino/ralphy/main/assets/install/install.ps1 | iex

The script downloads the newest release for your computer, checks its SHA-256, puts ralphy on your PATH, and ends with ralphy doctor. It needs no root and no administrator, and asks before it goes on as either. To also start the daemon at sign-in, end the Linux and macOS line with | RALPHY_DAEMON=1 sh, or on Windows run $env:RALPHY_DAEMON = '1' first. To read the script before it runs, download it, read it, then run the file. Run it again to repair an install.

Prefer to do it by hand? Grab the archive for your platform from the Releases page — Windows, Linux (x64 and ARM64), or macOS (Intel & Apple Silicon) — unzip it anywhere, then let it put itself on your PATH:

./ralphy install

It links ralphy into ~/.cargo/bin when you have one, otherwise ~/.local/bin. When that folder is not on your PATH, it adds it: to your shell start-up files on Linux and macOS, or to your user Path on Windows. Then open a new terminal. --no-modify-path leaves your PATH alone.

Already have it? ralphy update takes the newest release: it checks the published checksum, replaces the binary in place, and restarts the daemon if one is running. ralphy update --check just tells you what is new.

(Prefer to build from source? See docs/BUILDING.md.)

✅ 2 — The basics you'll need

• 🤖 At least one coding-agent CLI, signed in. That's the brain behind the terminals and the runs. Claude Code is the default; Codex, OpenCode, Copilot, Cursor, Gemini and Kimi work too. → which agents, and how to pick one
• 🐙 The gh CLI, logged in — needed for the issue board and the overnight run. Check with gh auth status. (Not using GitHub? The consoles, explorer, notes and changes work without it.)

No API keys anywhere. Git and Python must be installed too. ralphy doctor checks all of this and prints the version of each tool it finds.

🖥️ 3 — Start the workbench

ralphy daemon setup     # baptize it: pick a name and an avatar, mint an access token
ralphy daemon add .     # register the repo you're standing in (repeat per project)
ralphy daemon           # run it — then open http://127.0.0.1:7257

Open the page, pick your project in the sidebar, and open an agent from the Consoles menu. That's it: an agent is working on your machine, and you are watching it from a browser.

Want it up whenever you log in? ralphy daemon install registers it with your OS (Task Scheduler on Windows, a systemd user unit on Linux/WSL, a launchd agent on macOS), and ralphy daemon uninstall takes it back out. → docs/daemon.md

🧹 Uninstall

ralphy uninstall           # stop the daemon, remove ralphy, and take it off your PATH
ralphy uninstall --purge   # also delete ~/.ralphy (settings, token, peers, logs), after it asks

It keeps ~/.ralphy unless you add --purge, and it never changes a project's .ralphy/ folder or its GitHub labels.

---

🧰 What you can do in the workbench

🖥️ Work with many agents at once

Claude and Codex side by side on one project, and a second Claude in its own worktree.

• Consoles — actual agent CLIs running as terminals on a large stage you can pan. Group them into fences, or pop a fence out into its own window for a second monitor. Maximize one console and put others beside it as columns. Each console has a short name, such as myrepo #1, so you can tell them apart.
• Any command, not only agents — Run… opens a console with a command you type, such as htop or lazygit.
• One copy of the project per agent — create a git worktree from the branch picker or from a console's title bar. The agent works in its own folder, on its own branch, and never touches the files of another agent. Files, Changes and the diff follow the copy you pick. A new copy can take your .env and share node_modules. → worktrees
• See who needs you — a dot on each console and project shows whether the agent is working, waiting for your answer, or done. (Claude consoles today.)

📁 Read and ship the work

• 🗂️ Projects — every repo you registered, in one list: branch, uncommitted changes, and whether it has a GitHub remote.
• 📁 Explorer — the real file tree, with a real editor (Monaco): open, read, edit, save. Search file names or file contents. Open two files side by side. Images render inline, and files in any text encoding open and save correctly.
• 🌿 Changes — the working tree of the project or of a worktree: read the diff, stage, commit, fast-forward pull, and push when you say so.

📝 Keep your notes next to the agents

• Notes — markdown cards on the same stage as your consoles: task lists, tables, and diagrams (Mermaid). Each note is a file saved in your project. A note can stay on top of a maximized console while you work.

A fence groups consoles by task, even from different projects. The note is a file in the project, shown in its footer.

📊 Follow the work and the cost

The Board: read an issue without leaving the workbench. The ready-for-agent label is the one that puts an issue in the queue of the overnight run.

• 🧩 Board — your AFK/HITL backlog as a kanban. Open an issue, read it, and send it to a run without leaving the page.
• ▶️ Runs — the loop, live: which issue is being worked, which phase it's in (planning, executing, verifying), and what it cost.
• 📊 Spend — the token ledger and a dollar estimate, per run, per model, per project, and per worktree.
• 🛰️ Fleet — two daemons, one workbench: a WSL box (or a second machine) shows up as a peer, with its repos and its consoles.

Two consoles of the same repo on two screens is the point: you drive one agent by hand while Ralphy's run works the queue in the other.

---

📱 From any screen

Open the workbench on another device and you get the same sessions and the same layout. The consoles are made for touch too:

• On a phone, a maximized console uses the whole screen.
• A key bar gives you the keys a phone keyboard does not have: Esc, Tab, Shift, Enter, Ctrl and the arrows.
• Paste text or a screenshot straight into an agent.
• Lock a console or a fence, so a finger cannot move it by mistake.

 

OpenCode and Claude Code on a phone, through a tunnel, with the key bar at the bottom.

How to reach it

The workbench is a web app on your own machine, so anything that can reach that machine can open it. Ralphy has no cloud service in the middle: you choose how your machine is reached. Two ways, in order of least surprise:

• On your own network — bind it to a LAN address: ralphy daemon --bind 0.0.0.0. A non-loopback bind requires the access token minted by ralphy daemon setup, or the daemon refuses to start.
• From anywhere — put a tunnel in front of it (dev tunnels, ngrok, Cloudflare Tunnel). Tunnels that preserve the original hostname need you to declare it: ralphy daemon --allowed-host my-tunnel.example.dev. Declare the exact name, never a wildcard. This stops other websites from reaching your daemon through your browser (DNS rebinding).

Once it's reachable beyond loopback, turn on require-login: a password plus a code from an authenticator app (TOTP), enrolled from the Security panel with a QR you scan once. It's opt-in on purpose — Ralphy never decides for you how reachable your machine should be. → docs/daemon.md

---

🌙 The overnight run

The other half of Ralphy: point it at your GitHub issues and let it work them while you're asleep. For each issue it plans the work, lets an agent write the code, commits, re-runs the tests itself, and closes the issue if they pass. In the morning you skim the branch and merge what you like.

That's Geoffrey Huntley's "Ralph" loop — plan → execute → commit → verify → repeat — as a batteries-included implementation over your real issues, with guardrails so it's safe to leave running.

🏷️ Two labels decide everything

• 🟢 AFK (or ready-for-agent) — "away from keyboard, agent go." It joins the queue.
• 🔴 HITL (or ready-for-human) — "human in the loop." Ralphy never touches it.

Unlabeled issues are ignored. A few more labels fine-tune things (triage, staged plans, "stop before this one"), but those two are the daily driver. The full label rules →

▶️ Build trust one step at a time

ralphy init                              # guided setup: environment check, labels, repo prep

ralphy run --only-issue 13 --dry-run     # 1️⃣  plan one issue — no code, no commits
ralphy run --only-issue 13               # 2️⃣  actually do that one
ralphy run --deadline-hours 8            # 3️⃣  the whole queue, overnight

Once you trust it, this is the everyday shape of a run:

ralphy run --agent <agent> --branch-mode <current|new>

• 🤖 --agent — who writes the code. Same issues, different brain. You can also plan with one agent and write the code with another. → see all agents
• 🌿 --branch-mode — where the commits land. new (default) cuts a fresh afk/run-<stamp> branch so the branch you're on stays untouched; current commits right onto the branch you're already on. Either way Ralphy refuses to start on a dirty repo.

📖 Every other flag — deadlines, planning models, stopping before an issue — lives in the run options reference, and ralphy run --help prints the same list. ⏰ Want it on a timer? → docs/scheduling.md

💡 Turning an idea into a backlog

Ralphy works issues, so first you need some. Inside your agent, go from fuzzy to ready in three moves: grill-with-docs (co-author a short doc so the agent really understands what you want) → to-prd (shape it into a spec) → to-issues (split it into small, independent, labeled issues). ralphy init can install those skills for you.

🌅 The morning after

Open the Changes panel in the workbench and read the diff. Or use the shell:

git log --oneline origin/main..afk/run-<stamp>     # see what landed
git diff origin/main..afk/run-<stamp>

# 👍 Happy? Merge it.        # 👎 Not happy? Delete the branch —
git checkout main            #     your main was never touched.
git merge afk/run-<stamp>    git branch -D afk/run-<stamp>

🛡️ Why it's safe to leave running

• 🧹 Won't start on a dirty repo — your uncommitted work is never at risk.
• 🚫 The run never pushes and never opens a PR — it commits locally. Pushing is a deliberate act you take, from the workbench or the shell.
• ⏱️ Time budgets — a hung issue can't run forever.
• 🛑 Stops at the first failure — one stuck issue ends the run instead of burning the whole night, and hands you the branch as-is.
• ✅ Runner-enforced tests — an issue closes only when Ralphy itself watched the tests pass. → docs/verify-gate.md
• 🧯 Command guardrails — Claude Code sessions block git push, pull request writes, reset --hard and other destructive commands mid-run. Codex, OpenCode and Copilot sessions block pushes and pull request writes. Kimi, Cursor and Gemini rely on their own vendor's controls. → SECURITY.md
• 🗣️ Only your team talks to the agent — issue comments from people who are not collaborators on the repo never reach it.

---

🔒 What stays on your machine

• Your code, your sessions and your logins. Ralphy has no account, no cloud service of its own, and no telemetry.
• What does leave, and where it goes. Your prompts and the code the agent reads go to that agent's vendor, under your own login. Issue reads, comments and labels go to GitHub through gh. ralphy usage downloads model prices from models.dev. Telegram, the event sink and remote images in the workbench send data only after you turn them on.
• The files git and Ralphy own. The workbench cannot write into .git or .ralphy.
• Checking for updates is anonymous. The daemon asks GitHub for new releases every six hours, with nothing that identifies you. You can turn it off. → release watch
• You can check what you download. ralphy update refuses a file whose checksum does not match. To confirm a release archive was built by this repository: gh attestation verify <archive> --repo paulocorcino/ralphy.

---

📲 Keep an eye on it from your phone (optional)

Ralphy can post a live status card to a Telegram chat and keep it updated the whole way through a run — planning, coding, and the final summary. It also tells you when an agent in a console is waiting for your answer. It's read-only; the bot just tells you how things are going.

ralphy telegram setup    # store your bot token, then send /start to link your chat
ralphy telegram test     # send a ping to confirm it works

More on the Telegram monitor →

---

📚 More you can do

Documentation index: user guides, development rules, research and validation evidence.

Feature	What it's for	Start here
🖥️ The daemon & fleet	autostart, worktrees, WSL peers, reaching it remotely	docs/daemon.md
🤖 Choose your agent	seven vendors — even plan with one and code with another	docs/agents.md
🔍 The verify gate	why "green" means the tests actually passed, not the agent said so	docs/verify-gate.md
📊 Cost reporting	tokens per run, with a $ estimate	docs/usage-and-cost.md
⚙️ Persistent settings	stop retyping the same flags every run	docs/configuration.md
⏰ Scheduled runs	drain the queue nightly on a timer	docs/scheduling.md
📡 Event streaming	POST every run event to a dashboard or webhook	docs/events.md
🧠 Knowledge cache	Ralphy remembers hard-won setup facts across runs	ralphy consolidate --help
🏗️ Architecture	ports & adapters — the decisions, and why	docs/adr/

---

🙏 Credits

• The Ralph loop — the unattended plan-execute-commit pattern is Geoffrey Huntley's.
• Triage vocabulary — the labels (ready-for-agent, ready-for-human, …) are Matt Pocock's, from his engineering skills.

📄 License

GPLv3 — see LICENSE. Copyright (C) 2026 Paulo Corcino.