Docs/Start

Overview

Lumpcode runs your coding agent through work too big for one chat, one reviewable branch at a time. You need git and a CLI agent. There is no account and no database.

On this page
  1. What it does
  2. Where to start
  3. What it does not do
  4. Packages

What it does

Some work is a list, not a task: two hundred components to migrate, forty tickets, every module that has no test. You describe that list once as a lump, a folder in your repo with three things:

  • what to work on: a path pattern, a ticket folder, an API you query
  • what to tell the agent: one prompt, or several steps gated on your build or tests
  • which agent: Cursor, Claude Code, Copilot, Codex, OpenCode, or your own

Lumpcode takes the next unfinished item, runs the agent on it, commits the result, and pushes a branch. You open that branch as a pull request, fix it if the agent missed, and merge. The next run skips what you merged.

text
.lumpcode/lumps/portToVue/config.json     what to work on, what to prompt, which agent
          │
          ▼
worker (lumpcode start)                   next unfinished item, one branch
          │
          ▼
lump/portToVue/UserCard  →  PR  →  merge  →  next pass picks DataTable

On your laptop, lumpcode run rehearses the same loop in place on your current branch, so you can check the prompt before a worker takes over.

Where to start

First PRInstall, run lumpcode setup, rehearse one lump on your laptop. Leave a worker runningA second clone that keeps pushing branches while you review. ExamplesMigrations, issue queues, ticket backlogs, lumps that feed lumps. Watch it workDashboard, live transcripts, logs, and status from git.

What it does not do

  • It never merges. You do.
  • It stops at git push. Opening the pull request is yours, or opt-in with openPrPostTeardown.
  • It never pushes agent work to your main branch. Work lands on lump/<lumpName>/… branches.

Packages

Package Install when
@lumpcode/cli Always. This is the lumpcode command.
@lumpcode/cli-utils You write config.ts and want defineConfig and typed helpers.
@lumpcode/recipes You want retry loops, folder backlogs, or opening a PR after push.

Add the last two to the project package.json, not only globally, so a worker clone gets them from npm install.

Edit this page