DEV Community: Daniel Saadia

Turn a dupes report into small PRs with Lumpcode

Daniel Saadia — Thu, 20 Aug 2026 09:44:50 +0000

Lumpcode is a git-first loop manager: a small CLI that runs long agent campaigns over your own repo, in reviewable slices. Git is the gate (one PR at a time) and the source of truth (what is left is read from remote history, not a distant database). You describe the campaign once, merge what is good, and the next tick continues with the rest.

A lump is one campaign under .lumpcode/lumps/<name>/. Each context is one isolated unit of work: one branch, one PR. You can run a tick by hand, or leave a daemon on a machine that stays on.

This article is one campaign: a scanner finds repeated code; one lump proposes a single abstraction as a plan in git; a second lump implements it, with tests, until green. You merge small PRs; the loop does not finish.

The argument for why loops should plug into git is Codemods grew a brain. Our tooling didn't.. If you do not have a Lumpcode project yet, start with the dedicated daemon how-to.

Use /lumpcode in your agent session when you hit a config question (npx skills add lumpcode/skills).

1. What you are building

Two lumps, one backlog folder:

.lumpcode/lumps/abstractionFinder/     # scan + write one plan
.lumpcode/lumps/abstractionImplementer/
  backlogItems/
    todo/<utilName>/desc.yml
    todo/<utilName>/requirements.md
    completed/<utilName>/              # after a merged implementer run

Finder: one ephemeral context per tick. Reads a dupes report, writes todo/<name>/, does not implement.
Implementer: one backlog item that already has requirements.md → implement, refactor call sites, tests, retryUntilGreen → move to completed/.

Cap how many plans sit unmerged (maxPendingAbstractions, maximumNumberOfConcurrentBranches) so the finder does not outrun review.

2. Project deps

On the laptop repo (commit these before the dedicated clone needs them):

npm install --save-dev @lumpcode/cli-utils @lumpcode/recipes

The global CLI does not resolve recipes. If cli-utils / recipes are already in package.json from the daemon how-to, skip this.

3. Pick a scanner

The first finder step should be deterministic. For JS/TS, Fallow is the example:

npx fallow dupes --mode semantic --format json > .lumpcode/dupes.json

Point it at the package or tree you care about (-w @your/package if you use workspaces). Other languages: any tool that writes a report the agent can @. The lump only needs a file.

4. Scaffold the two lumps

lumpcode lump-create abstractionFinder --config ts
lumpcode lump-create abstractionImplementer --config ts

Replace the finder config. The shipped abstractionFinder recipe is a useful skeleton (ephemeralContextListFn, backlog path). Override steps so a scanner runs first, and so the prompt is about your tree, not Lumpcode's CLI package (the recipe default still mentions packages/apps/cli).

.lumpcode/lumps/abstractionFinder/config.ts:

import { abstractionFinder } from '@lumpcode/recipes';

const backlogItemsDir = '.lumpcode/lumps/abstractionImplementer/backlogItems';

export default {
    ...abstractionFinder({
        maxPendingAbstractions: 1,
        scanDirectories: ['src'],
        backlogItemsDir,
        command: 'cursor',
        maximumNumberOfConcurrentBranches: 1,
    }),
    steps: [
        {
            commandFn() {
                return {
                    executable: 'sh',
                    args: [
                        '-c',
                        'npx fallow dupes --mode semantic --format json > .lumpcode/dupes.json < /dev/null',
                    ],
                };
            },
        },
        {
            promptTemplate: `Read @.lumpcode/dupes.json and scan @src for duplicated logic (same pattern, not merely similar file structure).

List existing names under @${backlogItemsDir}/todo/ and @${backlogItemsDir}/completed/. Do not re-propose those names.

Pick exactly one new abstraction:
- A util name matching ^[a-zA-Z0-9_-]+$
- Refactoring all call sites in src/ should reduce net line count (excluding new unit tests)

Create exactly one folder @${backlogItemsDir}/todo/<utilName>/ with:
- desc.yml: name, task, priority (max todo priority + 1, or 1)
- requirements.md: problem, goals and non-goals, proposed API, affected files, acceptance criteria (net reduction + unit tests)

Do not implement product code.`,
        },
    ],
};

.lumpcode/lumps/abstractionImplementer/config.ts:

import { abstractionBacklog } from '@lumpcode/recipes';

export default abstractionBacklog({
    command: 'cursor',
    configUrl: import.meta.url,
    maximumNumberOfConcurrentBranches: 1,
    implValidateCommand: 'npm test',
});

Change command, scanDirectories, the Fallow invocation, and implValidateCommand (npm test && npm run build, a workspace -w, …). /lumpcode can reshape paths and prompts.

The implementer skips items without requirements.md. configUrl: import.meta.url is required so the recipe can resolve the project root.

5. Dry run

On the laptop (shared mode, checkout untouched):

lumpcode lump-plan abstractionFinder --plan --contexts
lumpcode lump-plan abstractionImplementer --plan --contexts

Finder should preview a scan + a prompt that writes a folder, not code. Implementer with an empty todo/ is a valid empty plan.

Optional: run one finder context and review the requirements PR before the implementer is allowed to code:

lumpcode run abstractionFinder

6. Merge the configs, let the daemon tick

Commit both lumps (and package.json / lockfile if you added recipes here), push, merge to your primary branch.

On the dedicated worker, npm install is already done if recipes were in the first project push. Then:

lumpcode start --include='abstractionFinder,abstractionImplementer'

Or 'abstraction*'. You do not restart for new backlog items. You do restart if you change local.json.

Default is one context per branch. Merge implementer PRs into primary. If you squash or rebase, keep the LUMP: abstractionImplementer - <name> line in the commit message. Drop it and Lumpcode treats that item as not done.

Finder stays eligible: new ephemeral contexts, same campaign.

7. Disable

In either config (or both):

disabled: true,

Push and merge. The next tick soft-skips that lump. The daemon stays up.

That's all. The loop is public in Lumpcode under .lumpcode/lumps/abstractionFinder/ and abstractionImplementer/. Follow along at x.com/ddyods.

Hands-on: dedicated Lumpcode daemon

Daniel Saadia — Thu, 20 Aug 2026 09:41:23 +0000

This article is that dedicated-daemon path. You author on your laptop. A second clone, that you do not develop in, runs the scheduler. When a lump lands on the primary branch, the worker picks it up.

The argument for why loops should plug into git is Codemods grew a brain. Our tooling didn't..

1. Requirements

The dedicated clone is a checkout you do not develop in. Put it on a remote machine if you want it to run forever. Pre-flight hard-resets that tree.

You need:

Git origin with fetch and push
A coding agent CLI on PATH (cursor-agent, copilot, claude, …), already logged in
Node 22+

Nothing else. No extra service to stand up.

Install the /lumpcode skill so your agent has current docs while you set this up and write configs:

npx skills add lumpcode/skills

Use /lumpcode in the session when you hit a config or CLI question.

2. Install the CLI

On both machines:

npm install -g @lumpcode/cli
lumpcode --version

3. Laptop: project setup, shared mode

From your day-to-day repo:

lumpcode project-setup --primaryBranch main

Use your real integration branch instead of main if that is what you merge to.

.lumpcode/local.json is gitignored and per machine. On the laptop it should be:

{
  "mode": "shared"
}

Shared mode never touches this checkout. Runs go to ~/.lumpcode/project-copies/<projectName>/.

Install @lumpcode/cli-utils and @lumpcode/recipes into this repo now, before the first push. Later TypeScript lumps import them from the project's node_modules (the global CLI does not ship them). If they are already in package.json when the dedicated clone is set up, that machine runs npm install once and does not need another install when the first lump lands.

npm install --save-dev @lumpcode/cli-utils @lumpcode/recipes

If the repo has no package.json yet, this creates a minimal one. Commit it with the Lumpcode project in the next step.

4. Push the Lumpcode project

Commit .lumpcode/project.json, the .gitignore updates, and package.json plus the lockfile. Do not commit local.json.

git add .lumpcode/project.json .gitignore package.json package-lock.json
git commit -m "Add Lumpcode project"
git push

Merge that to your primary branch if you are not already on it.

5. Dedicated clone: dedicated mode, then start

On the worker, clone (or pull) the same repo. .lumpcode/ is already there, so project-setup will refuse. Install project deps (this is the npm install that pulls in cli-utils and recipes):

npm install

Then write .lumpcode/local.json:

{
  "mode": "dedicated"
}

Then:

lumpcode start
lumpcode daemon-status

No lumps yet. That is fine. The default global daemon ticks every five minutes. When a lump appears on the primary branch, the next tick runs it. You do not restart for new lumps.

Do not edit product code in this clone.

6. First lump (laptop)

Back on the day-to-day repo. This example is a React → Vue migration, one component per context, with tests retried until green. cli-utils and recipes are already in the project from step 3.

lumpcode lump-create reactToVue --config ts

Replace .lumpcode/lumps/reactToVue/config.ts (adjust paths and command to your repo and agent):

import { defineConfig } from '@lumpcode/cli-utils';
import { retryUntilGreen, shellCommand } from '@lumpcode/recipes';

export default defineConfig({
    command: 'cursor',
    contextListJson: {
        FOLDER: 'src/components/{COMPONENT_NAME}/',
        COMPONENT: 'src/components/{COMPONENT_NAME}/{COMPONENT_NAME}.tsx',
        TEST: 'src/components/{COMPONENT_NAME}/{COMPONENT_NAME}.test.tsx',
    },
    steps: retryUntilGreen({
        steps: [
            {
                promptTemplate:
                    'Port @{COMPONENT} to Vue 3 <script setup> as {COMPONENT_NAME}.vue in @{FOLDER}. Port @{TEST} to Vitest + @vue/test-utils. Keep behavior identical.',
            },
        ],
        validationCommandFn: () => shellCommand('npm test'),
    }),
});

/lumpcode can help you reshape discovery and prompts.

7. Dry run, optional shared run

Still on the laptop:

lumpcode lump-plan reactToVue --plan --contexts

That loads the config, lists contexts, and previews the tick. It does not run the agent, branch, or push. Add --contextName Button to inspect one context.

If you want a real tick on one context, shared mode keeps your checkout untouched:

lumpcode run reactToVue

Default is one context per branch (the next eligible one). Review the pushed lump/reactToVue/… branch before you let the daemon loose.

8. Merge the lump to primary

When the plan (and optional shared run) look right, commit the lump, push, and merge to your primary branch.

The dedicated daemon fetches that branch on the next tick and starts. Recipes are already installed there from step 5.

9. Merge work branches

Each finished context is a branch lump/reactToVue/<contextName> with commit subject LUMP: reactToVue - <contextName>. Open a PR into the primary branch and merge as usual; if you squash or rebase, keep that LUMP: … line (drop it and Lumpcode treats the context as not done). Git is the record: Lumpcode scans remote history for that marker, so toDo means it is not on any remote ref, branchPushed means it is on a work branch, and finished means the marker is an ancestor of origin/<primaryBranch>. Merge the PR; the next tick skips that context and picks another.

10. Disable the lump

In the lump config:

disabled: true,

Push and merge. The next tick soft-skips it. The daemon stays up.

That's all. Once the worker is up, a next campaign is turning a dupes report into small PRs. Follow along at x.com/ddyods.