convez.ai
AgenteAutomaçãoIntermediário
paulocorcino

Ralphy

paulocorcino/ralphy

Automatize seu backlog GitHub com Claude Code enquanto dorme

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent 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/ralphy

1 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

Estrelas
6
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
—
Issues abertas
24
Contribuidores
1

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

Built with Rust Platform: Windows License: GPL v3 Powered by Claude Code

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).
  • gh authenticated — check with gh auth status.
  • The agent CLI for your --agent choice, signed in to its subscription (no API key):
    • claude (default) — Claude Code CLI
    • codex — signed in with codex login (use --agent codex)
    • opencode — a provider set up with opencode auth login (use --agent opencode)
  • The ralphy.exe binary on your PATH — 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:

  1. Plan — the agent reads the codebase and writes a .ralphy/plan.md you can inspect. On Claude, the plan also picks the execution model (a small model for mechanical work, a strong one for complex work). Issues labelled stagedplan are planned with the bundled staged-plan skill.
  2. 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.
  3. 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:

LabelWhat Ralphy does
ready-for-agent or AFKworks it, closes it when green
ready-for-human / HITLnever touched — not in the queue
stagedplanplanned with the staged-plan skill (still needs a queue label to be picked up)

Two extra controls:

  • ## Blocked by in 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-before label — 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 the stop-before label 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):

--agentRunsNotes
claude (default)Claude Code, live sessionMobile Remote Control, model routing, auto-resume on usage limits
codexcodex exec, headlessScales effort on one model; stops and reports on a usage limit
opencodeopencode run, headlessFixed 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-hours keep 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, and gh pr merge are 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

License

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

Ver o original no GitHub

Bom para

Relacionados