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)
• 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).

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.

{
  "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"
  }
}

5. Run once

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

lumpcode run myFirstLump

Preview without running the agent: lumpcode lump-plan myFirstLump.