● v0.1 A personal loop · CLI · agent-drivenUn loop personal · CLI · conducido por agentes

Your delivery, always flowing.Tu delivery, siempre fluyendo.

Once the agent can implement on its own, what is left is coordination: hand over the spec, launch the implementation, ask for the review, launch the next slice, one repetitive prompt at a time. grooveloop takes over that coordination — specs, slices, reviews and merges locked into one steady pulse. You decide; the loop makes sure nothing stalls. Cuando el agente ya implementa solo, lo que queda es coordinación: pasar la spec, lanzar la implementación, pedir la review, lanzar la siguiente slice, a golpe de prompt repetitivo. grooveloop se encarga de esa coordinación — specs, slices, revisiones y merges encajados en un solo pulso. Tú decides; el loop no deja que nada se pare.

You think the SpecTú piensas la Spec The loop coordinatesEl loop coordina You validate and steerTú validas y rediriges
grooveloop loop --repo acme/shop --workdir ~/code/shop
10:02 tick #88 · story #12 “Gift cards” · 3/6 slices merged
10:02 slice #15 “Balance in cart” dispatchable · deps ✓
10:03 dispatch developer (claude · sonnet) → run f3a9…
10:19 PullRequestOpened · PR #203 → under_review
10:21 reviewer verdict review:approve → pr_open · your turn
10:34 PullRequestMerged → dispatching #16 and #17
10:34 merge = approve · close = reject
The splitEl reparto

The loop coordinates. You decide.El loop coordina. Tú decides.

Walking an agent through a multi-slice change is coordination work, not engineering. The loop does it on every tick, with explicit rules you configure, and the state of every slice lives in its sub-issue labels. Nothing merges without you, unless you opt into --auto-merge. Conducir a un agente por un cambio de varias slices es trabajo de coordinación, no de ingeniería. El loop lo hace en cada tick, con reglas explícitas que tú configuras, y el estado de cada slice vive en las labels de su sub-issue. Nada se mergea sin ti, salvo que actives --auto-merge.

What the loop doesLo que hace el loop
pasting each slice into a promptcopiar cada slice en un prompt

Writes each assignmentRedacta cada encargo

One sub-issue per slice. The agent gets its profile, the Spec and the Story journal.Una sub-issue por slice. El agente recibe su perfil, la Spec y la bitácora de la Story.

deciding which slice goes nextdecidir qué slice va ahora

Respects the graphRespeta el grafo

A slice dispatches only when its dependencies are merged, capped by --max-parallel-slices.Una slice se despacha solo con sus dependencias mergeadas, con el tope de --max-parallel-slices.

waiting for the agent to finishesperar a que el agente acabe

Watches the runVigila la ejecución

Each agent runs detached in its own worktree. The cockpit flags a silent agent as stalled.Cada agente corre detached en su propio worktree. El panel de control marca al agente silencioso como stalled.

doing the first review passhacer la primera pasada de revisión

Reviews before youRevisa antes que tú

A second agent reads the diff once and leaves its verdict as a label. Your PR arrives pre-screened.Un segundo agente lee el diff una vez y deja su veredicto en una label. La PR te llega con el filtro hecho.

asking for the obvious fixespedir las correcciones obvias

Fixes what blocksCorrige lo bloqueante

On a blocking verdict, the loop dispatches the correction, up to --max-review-rounds rounds.Ante un veredicto bloqueante, despacha la corrección, hasta --max-review-rounds rondas.

remembering to launch the next oneacordarte de lanzar el siguiente

Continues after your mergeContinúa tras tu merge

The tick detects your merge and dispatches whatever the graph frees. The Story closes when nothing is left alive.El tick detecta tu merge y despacha lo que el grafo libera. La Story se cierra cuando no queda nada vivo.

What stays yoursLo que queda tuyo
Before · creativeAntes · creativo

You think the changePiensas el cambio

You brainstorm and close it into a Spec: one Issue with its slices, their order and their dependencies.Haces el brainstorming y lo cierras en una Spec: una Issue con sus slices, su orden y sus dependencias.

  • The grooveloop:slicing skill helps you cut small, safe slices.La skill grooveloop:slicing te ayuda a cortar slices pequeñas y seguras.
  • Every doubt resolved in the spec is one correction or redirection less once the code is written.Cada duda resuelta en la spec es una corrección o una redirección menos cuando el código ya está escrito.
  • You mark the Issue ready; the loop picks it up.Marcas la Issue como lista y el loop la recoge.
After · importantDespués · importante

You validate and steerValidas y rediriges

You review each PR on GitHub web, as you already do. If the agent took a path you don't want, you mark another one. Your decision is the only thing that moves the loop forward.Revisas cada PR en GitHub web, como ya haces. Si el agente tomó un camino que no quieres, le marcas otro. Tu decisión es lo único que hace avanzar el loop.

  • /grooveloop-implement sends the agent back with your comments./grooveloop-implement devuelve al agente con tus comentarios.
  • Small increments keep each review manageable, and make each merge safe to take to production.Los incrementos pequeños mantienen cada review manejable y permiten llevar cada merge a producción de forma segura.
  • merge approves and close rejects. A rejected slice keeps its branch: the loop never deletes work.merge aprueba y close rechaza. Una slice rechazada conserva su rama: el loop nunca borra trabajo.
  • /grooveloop-learn turns a redirection into a repo convention, via a PR you review./grooveloop-learn convierte una redirección en convención del repo, vía una PR que tú revisas.

You decide. The agent works for you, following your rules.Tú decides. El agente trabaja para ti, siguiendo tus reglas.

Conventions & learningConvenciones y aprendizaje

The repo teaches the agent — and learns from you.El repo enseña al agente — y aprende de ti.

Autonomy without rules produces code you don't want. The real contract is in the repo: conventions that say how an agent works your code — architecture, style, testing, process. And they are living documents: every time you steer, the loop offers to distill the lesson back into them. La autonomía sin reglas produce código que no quieres. El contrato real está en el repo: convenciones que dicen cómo trabaja un agente tu código — arquitectura, estilo, testing, proceso. Y son documentos vivos: cada vez que rediriges, el loop ofrece destilar la lección de vuelta a ellas.

The repoEl repo

Declares its conventionsDeclara sus convenciones

CLAUDE.md and docs/conventions/ per layer: domain, application, infrastructure, testing. The agent reads them before touching code.CLAUDE.md y docs/conventions/ por capa: dominio, aplicación, infraestructura, testing. El agente las lee antes de tocar código.

grooveloop

Works inside themTrabaja dentro de ellas

The developer follows them; the reviewer measures the diff against them. Convention beats general best practice.El developer las sigue; el revisor mide el diff contra ellas. La convención gana a la best practice general.

YouTú

Steer in the PRRediriges en la PR

Something doesn't fit? Comment and write /grooveloop-implement. The agent redoes it your way.¿Algo no encaja? Comenta y escribe /grooveloop-implement. El agente lo rehace a tu manera.

grooveloop

Distills the lessonDestila la lección

/grooveloop-learn hands your redirection to the scribe, which uses the grooveloop:conventions skill to open a conventions PR you review. One correction, never twice./grooveloop-learn pasa tu redirección al scribe, que con la skill grooveloop:conventions abre una PR de convenciones que tú revisas. Una corrección, nunca dos veces.

↻The merged convention feeds step 01: the next slice is already born knowing it.La convención mergeada alimenta el paso 01: la siguiente slice ya nace sabiéndola.
Agents & capabilitiesAgentes y capacidades

The agents are yours to shape.Los agentes se moldean a tu medida.

Every role in the loop — developer, reviewer, verifier, scribe — is an agent profile in markdown: readable, versionable, overridable per repo. Cada rol del loop — developer, reviewer, verifier, scribe — es un perfil de agente en markdown: legible, versionable y sobreescribible por repo.

  • Persona and engine. Each profile declares who the agent is, which engine runs it (claude, opencode) and with which model.Persona y motor. Cada perfil declara quién es el agente, qué motor lo ejecuta (claude, opencode) y con qué modelo.
  • Skills and context, for any agent. A profile lists the skills the agent loads and the context files it reads before it starts: your conventions, your TDD workflow, your review checklist.Skills y contexto, para cualquier agente. Un perfil lista las skills que el agente carga y los ficheros de contexto que lee antes de empezar: tus convenciones, tu workflow de TDD, tu checklist de revisión.
  • Per-repo override. A profile in .grooveloop/agents/ inside the workdir overrides the packaged default field by field: it declares what changes and inherits the rest. Each repo tunes its own crew.Override por repo. Un perfil en .grooveloop/agents/ dentro del workdir sobrescribe el default del paquete campo a campo: declara lo que cambia y hereda el resto. Cada repo afina su propio equipo.
  • A Claude Code plugin. grooveloop:setup prepares a repo, grooveloop:slicing writes the spec, grooveloop:verify checks a deploy and grooveloop:conventions keeps the conventions in shape.Un plugin de Claude Code. grooveloop:setup prepara un repo, grooveloop:slicing escribe la spec, grooveloop:verify comprueba un despliegue y grooveloop:conventions mantiene las convenciones en forma.
# .grooveloop/agents/developer.md
---
engine: claude
model: sonnet
skills:
  - test-driven-development
  - verification-before-completion
context_files:
  - docs/conventions/domain.md
  - docs/conventions/testing.md
---
You implement one slice at a time.
Plan first. Tests before code. Open
a small PR that closes the sub-issue.

Deploy verificationVerificación del despliegue

With --verify-deploy, the verifier checks after the merge that the deploy does not degrade the service and that the slice does what it promised.Con --verify-deploy, el verifier comprueba tras el merge que el despliegue no degrada el servicio y que la slice hace lo que prometía.

Cost in plain sightCoste a la vista

Every agent session shows model, tokens, cache %, turns and dollars. grooveloop usage gives the real cost per slice.Cada sesión de agente muestra modelo, tokens, % de caché, turnos y dólares. grooveloop usage da el coste real por slice.

State lives in labelsEl estado vive en labels

GitHub is the source of truth: each slice moves pending → dispatched → under_review → pr_open → merged, and issues, sub-issues, labels and PRs hold that state. Anyone on the team reads it with no extra tooling.GitHub es la fuente de verdad: cada slice pasa por pending → dispatched → under_review → pr_open → merged, e issues, sub-issues, labels y PRs guardan ese estado. Cualquiera del equipo lo lee sin herramientas extra.

A shared Story journalBitácora de la Story

Agents working one Story share a journal (note, journal). The reviewer and the next slice know what was decided before.Los agentes de una Story comparten bitácora (note, journal). El revisor y la siguiente slice saben qué se decidió antes.

No server, no brokerSin servidor ni broker

A local CLI. Each tick queries GitHub and detects events. No webhooks, queues or databases to run.Un CLI local. Cada tick consulta GitHub y detecta los eventos. Sin webhooks, colas ni bases de datos que mantener.

Preflight before workPreflight antes de trabajar

grooveloop doctor probes every adapter: GitHub auth, engines and profiles. If something fails, nothing dispatches.grooveloop doctor comprueba cada adaptador: autenticación de GitHub, motores y perfiles. Si algo falla, no se despacha nada.

The cockpitEl panel de control

A TUI cockpit, not a scrolling log.Un panel de control en la terminal, no un log que corre.

grooveloop watch opens a terminal app over the live loops on your machine. Three views, one question each — where each slice stands and what its PR waits for, what was specified, what was decided along the way. Keyboard-driven, and it never touches GitHub: it only reads the state files each loop publishes. Walk the views below. grooveloop watch abre una app de terminal sobre los loops vivos de tu máquina. Tres vistas, una pregunta cada una — dónde está cada slice y qué espera su PR, qué se especificó, qué se decidió por el camino. Se conduce con el teclado y nunca toca GitHub: solo lee los ficheros de estado que publica cada loop. Recorre las vistas abajo.

grooveloop watch · acme/shop › #12 Gift cards › 4 Checkout UI
LOOPS · 1 alive
▶ acme/shop
tick ok · 35s ago · 13s
▶ 1 agent · 12m · $3.08
⏳ PR #207 awaits review
NO LOOP
acme/billing 3h ago
acme/catalog 2d ago
#12 Gift cards ▼
SlicesSpecJournal
#12 Gift cards WIP · 1 pending · 1 dispatched · 1 pr_open · 3 merged
1 Schema: gift_cards table ● merged #203
✓ implement_slice sonnet ⏱ 9m12s $2.10 ▸ 12t 2sk 0sub 31tl
✓ review_slice opus ⏱ 2m40s $0.84 ▸ 9t 1sk 0sub 14tl
2 Redeem API ← 1 ● merged #204
✓ implement_slice sonnet ⏱ 14m05s $3.45 ▸ 24t 3sk 0sub 52tl
✓ review_slice opus ⏱ 3m31s $1.02 ▸ 11t 1sk 0sub 17tl
✓ lesson #19 learned → PR #205
3 Balance in cart ← 2 ● merged #206
✓ implement_slice sonnet ⏱ 11m48s $2.87 ▸ 19t 2sk 0sub 40tl
✓ review_slice opus ⏱ 3m02s $0.91 ▸ 10t 1sk 0sub 15tl
4 Checkout UI ← 3 ◐ pr_open #207
↯ implement_slice sonnet ⏱ 6m40s $1.37 ▸ — interrupted
✓ implement_slice sonnet ⏱ 18m24s $4.20 ▸ 38t 3sk 0sub 61tl resumed
✓ review_slice opus ⏱ 4m12s $1.12 ▸ 14t 1sk 0sub 22tl minor
5 Emails ← 2 ◔ dispatched
▶ implement_slice sonnet ⏱ 12m07s $3.08 ▸ 21t 2sk 0sub 44tl LIVE
↳ Bash uv run pytest tests/emails -q
6 Analytics ← 4, 5 ○ pending
Slice 4 · PR #207
PRDiffComments 2
#207 feat(checkout): gift card balance at
payment step
+184 −23 · 9 files · checks ✓
mergeable ✓ · updated 12m ago
synced 40s ago
verdict review:minor · round 0 of 3
pre-human reviewer, before your turn
summary Totals recompute once; MoneyField
reused; e2e added. Minor: rename
the helper.
your turn · merge = approve · close = reject
steer with a comment + /grooveloop-implement
⏎ expand tab focus [ prev Story ] next Story o open in GitHub f filter q quit

Slices — the Story live: every slice with its order, dependencies, state and PR, and under it every agent session — outcome, model, elapsed, cost, turns, skills, tools — plus the live agent's last action and the lessons it left. The slice under your cursor shows its pull request on the right: size, checks, mergeability, the reviewer's verdict, and the Diff and Comments tabs where you steer with /grooveloop-implement.la Story en vivo: cada slice con su orden, dependencias, estado y PR, y debajo cada sesión de agente — resultado, modelo, duración, coste, turnos, skills, tools — más la última acción del agente vivo y las lecciones que dejó. La slice bajo tu cursor muestra su pull request a la derecha: tamaño, checks, mergeabilidad, el veredicto del revisor, y las pestañas Diff y Comentarios donde diriges con /grooveloop-implement.

Example data — your repos, Stories and costs take their place.Datos de ejemplo — tus repos, Stories y costes ocupan su lugar.

InstallInstalar

From install to the first tick.De la instalación al primer tick.

  • Python 3.13 and uvPython 3.13 y uv
  • GitHub CLI authenticated (gh auth login)GitHub CLI autenticado (gh auth login)
  • An agent engine: Claude Code or opencodeUn motor de agentes: Claude Code u opencode
  • A GitHub repo with Issues and sub-issues, and a local checkout of itUn repo de GitHub con Issues y sub-issues, y un checkout local
  • One Issue with a Spec and its ## Slices: grooveloop:slicing writes it with youUna Issue con una Spec y su ## Slices: grooveloop:slicing la escribe contigo
installinstalar
$ uv tool install grooveloop
pluginplugin
$ claude plugin marketplace add pasmontesinos/grooveloop
$ claude plugin install grooveloop@grooveloop
# then ask Claude Code to prepare the repo with grooveloop:setup# después pide a Claude Code que prepare el repo con grooveloop:setup
preflight
$ grooveloop doctor
# probes GitHub auth, engines and agent profiles# comprueba GitHub, motores y perfiles de agente
run
$ grooveloop loop --repo acme/shop --workdir ~/code/shop
# in another terminal: the cockpit# en otra terminal: el panel de control
$ grooveloop watch
tick · 120s
The storyLa historia

My way of working with agents, turned into a tool.Mi forma de trabajar con agentes, convertida en herramienta.

I used to steer the agent in real time, in the same session where the code was being written. As models got better and the repository conventions sharpened with every correction I wrote down, it made more sense to put the weight on the spec and delegate the implementation, until it ran on autopilot up to the pull request. What was left was coordination: handing over the spec, launching, reviewing, launching the next slice, one repetitive prompt after another. grooveloop was born to replace that coordination. Correction rounds, parallel slices and lessons came later, almost on their own. Antes dirigía al agente en tiempo real, en la misma sesión en la que se escribía el código. A medida que los modelos mejoraban y las convenciones del repositorio se afinaban con cada corrección que dejaba por escrito, tenía más sentido poner el peso en la spec y delegar la implementación, hasta que fue en piloto automático hasta la pull request. Lo que quedaba era coordinación: pasar la spec, lanzar, revisar, lanzar la siguiente slice, a golpe de prompt repetitivo. grooveloop nació para sustituir esa coordinación. Las rondas de corrección, las slices en paralelo y las lecciones llegaron después, casi solas.

It is not a loop to hand everything over to the agents. It is a loop with control and continuous improvement: you think the spec, your merge is the decision, and every redirection can become a convention the next slice already knows. No es un loop para delegarlo todo en los agentes. Es un loop con control y mejora continua: tú piensas la spec, tu merge es la decisión, y cada redirección puede convertirse en una convención que la siguiente slice ya conoce.

in daily useen uso diario experimentsexperimentos personal projectsproyectos personales high-impact production projectsproyectos con alto impacto en producción
Why the namePor qué el nombre

groove

I am a percussionist. In a musical ensemble, percussion holds the pulse from inside, and everyone locks into it. That steady feel is the groove. The word comes from the groove of a vinyl record, where the needle follows the track without skipping.Soy percusionista. En una agrupación musical, la percusión sostiene el pulso desde dentro, y todos encajan en él. Esa sensación estable es el groove. La palabra viene del surco de un disco de vinilo, por donde la aguja avanza sin saltar.

groove loop

For a producer, the rhythmic pattern that repeats in a loop and carries the song while everything else is built on top. For a developer, a reconciliation loop: on each tick it reads GitHub, detects what changed and acts.Para un productor, el patrón rítmico que se repite en bucle y sostiene la canción mientras todo lo demás se construye encima. Para un desarrollador, un bucle de reconciliación: en cada tick lee GitHub, detecta qué ha cambiado y actúa.

grooveloop

The loop that keeps a change in the groove, from spec to merge, so that nothing stalls between one step and the next.El loop que mantiene un cambio en el groove, de la spec al merge, para que nada se atasque entre un paso y el siguiente.

You bring the ideas.
The loop keeps them in the groove.
Tú pones las ideas.
El loop las mantiene in the groove.