Get started : From install to the first PR

1. Prerequisites

You already have a git repo. This walkthrough starts AI loops on it.

• 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. Setup commits the Lumpcode files; typing c after a shared run stamps LUMP markers.
• A CLI coding agent on PATH (Cursor, Copilot, Claude Code, Codex, or OpenCode). If none is installed, setup waits for a command tag.
• 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: the skill

Helps the agent in your editor write and update lumps. Call the skill /lumpcode in your agent's session. Not used when a lump runs. lumpcode setup offers this install; you can also run it yourself.

npx skills add lumpcode/skills

3. Run setup

From the repo root, on the branch you want to rehearse on. Setup is interactive (a TTY, not --json). It scaffolds .lumpcode/, asks JSON, JavaScript, or TypeScript (JSON is the simple path; js/ts installs @lumpcode/cli-utils and @lumpcode/recipes), writes a first lump (README when that file exists), pauses so you can edit, commits and pushes the allowlisted files, plans, then runs in place on this branch.

lumpcode setup

When it pauses, reshape the stub toward files in this repo. A first campaign is often AI coding refactoring, a migration, or a small docs pass. 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"
  }
}

CI and scripts that cannot prompt should keep using flags-only lumpcode project-setup.

4. Rehearse on this branch

Shared setup runs the agent on the branch you are on. It does not create a lump/… branch and does not open a pull request. Verify the updates. Type c to stamp LUMP: myFirstLump - … markers (still no push), or e to leave the tree dirty and run again. Then push this branch yourself.