Ralphy
paulocorcino/ralphy
Automatize seu backlog GitHub com Claude Code enquanto dorme
Ver no GitHubAgent que automatiza o backlog de issues do GitHub durante a noite usando Claude Code. Planeja, codifica, faz commits e fecha issues, deixando uma branch pronta para revisão manual. Não faz push nem abre PRs automaticamente.
Instalação
npx convez-ai paulocorcino/ralphy1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Processar automaticamente issues rotuladas para um agent trabalhar
- Revisar código gerado por AI antes de merges
- Executar múltiplas issues com limite de tempo configurável
- Integrar fluxo de trabalho de coding agents em repositórios existentes
Veredito

Ferramenta Windows robusta e bem pensada que dá controle real ao desenvolvedor: automatiza work sem abrir PRs, permitindo revisão antes de merge. Requer setup inicial (CLI agents, gh auth) e repositório limpo, mas o tradeoff é segurança e confiança no fluxo overnight.
README
A tradução para o português deste README ainda está na fila.
Ralphy
Ralphy works your GitHub issue backlog while you sleep — and hands you a branch to review in the morning.
You label the issues you trust an agent to handle. Ralphy plans each one, has a coding agent write the code, commits the work, and closes the issue when it's green. It never pushes and never opens a PR — you review the branch and merge by hand. It runs on your coding-agent subscription (Claude, ChatGPT/Codex, or your OpenCode provider — no API key, so no per-token bill).
Scope (for now): Ralphy is a Windows tool. It drives one coding-agent CLI per run, picked with
--agent: Claude Code (the default), Codex, or OpenCode.
You, before bed: Ralphy, overnight: You, morning:
┌──────────────────────────┐ ┌────────────────────────┐ ┌────────────────────────┐
│ label issues you trust │ ──────▶ │ plan → code → commit │ ───▶ │ review the branch, │
│ an agent to handle │ │ → close, issue by issue│ │ merge what you like │
└──────────────────────────┘ └────────────────────────┘ └────────────────────────┘
Quick start
# 1) Try one issue, plan only — no code changes, no commits. Inspect .ralphy/plan.md.
ralphy run --repo C:\Dev\foo --only-issue 13 --dry-run
# 2) Run that one issue for real. Commits land on a fresh afk/run-<stamp> branch.
ralphy run --repo C:\Dev\foo --only-issue 13
# 3) The overnight run: the whole queue, ascending order, with an 8-hour budget.
ralphy run --repo C:\Dev\foo --deadline-hours 8
--repo defaults to the current directory, so from inside the repo you can just run
ralphy run --only-issue 13. Work the same setup up incrementally: --dry-run one
issue, then one issue for real, and only then trust the unattended overnight queue.
Prerequisites
- A clean working tree in the target repo (Ralphy refuses to start on uncommitted
work) and a reachable base branch (default
origin/main). ghauthenticated — check withgh auth status.- The agent CLI for your
--agentchoice, signed in to its subscription (no API key):claude(default) — Claude Code CLIcodex— signed in withcodex login(use--agent codex)opencode— a provider set up withopencode auth login(use--agent opencode)
- The
ralphy.exebinary on yourPATH— see docs/BUILDING.md. - Whatever build tools the issues themselves need on
PATH(an issue that builds a feature needs that feature's deps, or it will time out).
Ralphy works in place on whatever repo you point --repo at — no worktree, so your
warm build cache (target/, node_modules, …) is reused.
How it works
For every queued issue, in ascending number order:
- Plan — the agent reads the codebase and writes a
.ralphy/plan.mdyou can inspect. On Claude, the plan also picks the execution model (a small model for mechanical work, a strong one for complex work). Issues labelledstagedplanare planned with the bundledstaged-planskill. - Execute — the agent works the plan and commits each step. On Claude you can
follow along and step in from the Claude mobile app (each session is named
ralphy-<n>); Codex and OpenCode run quietly in the background. - Close on green — once the issue is done, Ralphy closes it with a comment pointing at the run branch. You still merge by hand.
If an issue doesn't finish cleanly (blocked, stuck, or out of time), the whole run stops and hands you the branch as it stands — so one bad issue can't burn the rest of the night. Finished issues stay committed; the stalled one's partial work is left for you to inspect.
Which issues get worked
An issue is in the queue if it carries any queue label. The defaults are
ready-for-agent and its shorthand AFK:
| Label | What Ralphy does |
|---|---|
ready-for-agent or AFK | works it, closes it when green |
ready-for-human / HITL | never touched — not in the queue |
stagedplan | planned with the staged-plan skill (still needs a queue label to be picked up) |
Two extra controls:
## Blocked byin the issue body — if it names an issue that's still open, Ralphy skips the issue (later ones still run) until the blocker is closed.stop-beforelabel — put it on a queued issue and the run stops before working it; every earlier issue still runs. Remove it and re-run to continue. (Create thestop-beforelabel in your repo first.)
--queue-label (repeatable) replaces the default label set entirely.
Choosing an agent
--agent picks the CLI for the whole run (default claude):
--agent | Runs | Notes |
|---|---|---|
claude (default) | Claude Code, live session | Mobile Remote Control, model routing, auto-resume on usage limits |
codex | codex exec, headless | Scales effort on one model; stops and reports on a usage limit |
opencode | opencode run, headless | Fixed model; set effort with --exec-variant; stops and reports on a usage limit |
All three run on a subscription, not a metered API key — Ralphy makes sure your
subscription login stays the one in charge. The same reviewer and staged-plan skills
ship to every agent automatically, so a run never depends on what's installed on your
machine, and your global skills are left untouched.
Everyday flags
ralphy run --agent codex # use Codex instead of Claude
ralphy run --agent opencode # use OpenCode
ralphy run --base-branch feature/x # cut the run branch from another base
ralphy run --branch-mode current # commit onto the current branch (no new branch)
ralphy run --exec-model opus # force the execution model for every issue
ralphy run --exec-variant high # OpenCode effort passthrough
ralphy run --no-remote-control # turn off mobile Remote Control (Claude)
ralphy run --queue-label my-label # use your own queue label
ralphy run --no-telegram # mute the Telegram monitor for this run
Run ralphy run --help for the full list (planning model/effort, time budgets, and
more).
Branch modes
--branch-mode new (the default) cuts a fresh afk/run-<stamp> branch from
--base-branch and commits every issue onto it, leaving your current branch untouched.
--branch-mode current commits straight onto the branch you're already on. Either way a
clean working tree is required. For issues that need different bases, run twice with
different --base-branch.
Morning review
git -C C:\Dev\foo log --oneline origin/main..afk/run-<stamp> # what landed
git -C C:\Dev\foo diff origin/main..afk/run-<stamp> # the full diff
# happy with it?
git -C C:\Dev\foo checkout main; git -C C:\Dev\foo merge afk/run-<stamp>
# not happy? just delete the branch:
git -C C:\Dev\foo branch -D afk/run-<stamp>
If the run stopped (didn't finish green), the repo is left on the run branch so you can fix the stalled issue in place, then commit and continue.
Knowledge cache and consolidation
Every green close leaves a note at .ralphy/knowledge/issue-<N>.md with the
environment facts and working commands extracted from the issue's handoff —
future sessions read these instead of re-deriving environment procedures. The
folder grows across runs, and the same trap naturally gets re-recorded by
several issues. Periodically (end of a milestone, or when the loose notes pile
up), curate it:
ralphy consolidate --repo C:\Dev\foo
A one-shot agent session (Claude) merges all loose notes into a single
.ralphy/knowledge/KNOWLEDGE.md — organized by topic, deduplicated, with
provenance — and the consumed notes are archived under knowledge/raw/.
Planner and executor sessions read KNOWLEDGE.md first, then any newer loose
notes. If the session fails or produces nothing, the notes stay loose for a
retry.
Running unattended, safely
Ralphy is built to run while you sleep, so it ships its own guardrails:
- Clean-tree precondition — it won't start on a dirty working tree, so it never clobbers uncommitted work, and the agent is kept on the run branch.
- Never pushes, never opens a PR — the agent only commits locally. The single run branch is the delivery; you review and merge it by hand.
- Time budgets — a per-issue limit (
--max-minutes-per-issue, default 90) and a global--deadline-hourskeep a hung issue from running forever. - Stop at first failure — one stalled issue stops the run instead of burning the rest of the budget.
- Command guardrails (Claude) — destructive commands like
git push,reset --hard, branch switches, andgh pr mergeare blocked. For Codex/OpenCode, safety rests on the isolated run branch and the built-in self-review.
Usage limits
There's no dollar cap to set — there's no API spend. On Claude and Codex, when you
hit a usage limit Ralphy waits for the reset and resumes the same issue automatically
(pass --stop-on-limit if you'd rather it stop and report). Both emit a trustworthy reset
time — Codex an absolute timestamp, Claude a relative one. OpenCode always stops and
reports — re-run once the limit clears.
Telegram run monitor (optional)
Since a run is unattended, Ralphy can post a live status card to a Telegram chat and
keep it updated through the whole run — planning, execution, usage-limit waits, and the
final summary — with a quick ping at the moments that matter. It's read-only; the bot
just reports. Once set up it's on by default for real runs; mute one run with
--no-telegram.
ralphy telegram setup # store the bot token, then send /start to capture your chat
ralphy telegram test # send a ping to confirm it works
ralphy telegram status # show the configured chat and a masked token
ralphy telegram disable # remove the stored config
Credits
- The Ralph loop — the unattended plan-execute-commit pattern is Geoffrey Huntley's.
- Triage vocabulary — the canonical labels (
ready-for-agent,ready-for-human, …) are Matt Pocock's, from his engineering skills.
License
GPLv3 — see LICENSE. Copyright (C) 2026 Paulo Corcino.