Get started : From install to the first PR

1. Prerequisites

• Node.js 22+
• A git repo with origin you can push to, and a primary branch that already exists on that remote (usually main)
• Git user.name and user.email set. Lumpcode writes commits.
• A CLI coding agent on PATH (Cursor, Copilot, Claude Code, Codex, or OpenCode)
• Awareness that lumpcode run invokes that agent (LLM cost)

2. Install the CLI

Puts lumpcode on your PATH. This is what runs a lump.

npm install -g @lumpcode/cli

2b. Optional: install the skill

Helps the agent in your editor write and update lumps. Call the skill /lumpcode in your agent's session to help it write and update lumps. Not used when a lump runs.

npx skills add lumpcode/skills

3. Initialize a project and create a lump

From the repo root. project-setup writes .lumpcode/project.json (commit this) and .lumpcode/local.json (per machine, gitignored). Default primary branch is main. If this repo merges on something else, pass it: lumpcode project-setup --primaryBranch dev.

lumpcode project-setup
lumpcode lump-create myFirstLump

4. Point the lump at real work

Edit .lumpcode/lumps/myFirstLump/config.json. This replaces the stub lump-create wrote. Change the path templates to files that exist in this repo. The snippet below is the same shape as the landing example; it only matches if you have src/components/{NAME}/. To confirm remotes and the agent first, use the README smoke test instead.

{
  "contextListJson": {
    "COMPONENT": "src/components/{NAME}/index.tsx",
    "TEST": "src/components/{NAME}/index.test.tsx"
  },
  "prompt": {
    "promptTemplate": "Port @{COMPONENT} to Vue 3 and update @{TEST}.",
    "command": "cursor"
  }
}

Commit .lumpcode/project.json and the lump folder. Push before you set up a worker: that clone only sees what is on the remote.

5. Preview, then run

Preview without calling the agent. If the context list is empty, the path templates do not match this repo. Fix them before you run.

lumpcode lump-plan myFirstLump --contexts
lumpcode run myFirstLump

run invokes the agent on one context, writes a LUMP: myFirstLump - … marker commit, and pushes a lump/myFirstLump/… branch. Open that as a PR.