Docs/Start

Core terms

The words Lumpcode uses, once, so the rest of the docs can stay short.

On this page
  1. The five you need
  2. Status
  3. Three folders a run can touch
  4. Branches Lumpcode cares about
  5. Words you will see in the CLI

Lumpcode has a small vocabulary. If a later page feels dense, it is usually because one of these five is doing more work than it looks.

The five you need

Term Meaning
Project A git repo that contains both .git/ and .lumpcode/. lumpcode project-setup creates the second folder.
Lump One campaign, at .lumpcode/lumps/<lumpName>/. Config, prompts, and hooks live here.
Context One unit of work inside a lump: a file, a group of files, a ticket, a package. It has a name and string variables that fill {VAR} in prompts.
Marker commit The commit Lumpcode writes for a finished context. The subject is LUMP: <lumpName> - <contextName>. Status is that string on your git remote, nothing else.
Worker The dedicated clone you do not edit (mode: dedicated). You leave it running. Daemons on that machine do the scheduled work.

A context is not “one file” by definition. One context can hold a component plus its test. Several contexts can share one branch when you set numberOfContextsPerBranch.

Status

Each context is in exactly one of three states, read from remote git history:

  1. toDo — no marker commit for this context on any remote ref yet.
  2. branchPushed — the marker exists on a branch other than the integration branch.
  3. finished — the marker is an ancestor of origin/<baseBranch>, usually because you merged the PR.

Re-running a lump is resumable: finished contexts are skipped. branchPushed is not finished. A later context that dependsOnContexts the first one waits until you merge.

If you squash and drop the LUMP: … line, Lumpcode forgets the work and the context looks toDo again. Keep the line in the squash message, or mark it finished with lumpcode context-status <lumpName> <contextName> --setToFinished.

Three folders a run can touch

Name Where What it is for
Project workspace Your repo Config, status cache, history. Same folder as the execution workspace.
Execution workspace This clone Shared run stays on HEAD (no reset). Dedicated pre-flight fetch / switch / hard-reset.
Branch workspace Shared: HEAD. Dedicated: same as execution (checkout), or .lumpcode/worktrees/<branch>/ (worktree) Where the agent runs. Dedicated git add / git commit happen here.

On a laptop, keep mode: "shared" so run rehearses on this branch. On a worker clone you never edit, mode: "dedicated" is the point. Details: local config.

Branches Lumpcode cares about

  • Primary branch — the integration line from .lumpcode/project.json (often main or dev). Local config can override it.
  • Base branch — the branch this lump’s work branches off, and the branch whose remote history counts as finished. Usually the primary. Set a lump baseBranch only when this campaign should land somewhere else.
  • Work branch — shared run stays on HEAD. A dedicated worker uses lump/<lumpName>/<contextName> by default. That is what you open as a PR.

Dedicated workers can scan several primary lines (dev plus feature/*). Shared mode on your laptop does not. See how a run works and local config.

Words you will see in the CLI

The worker is the machine (the dedicated clone). A daemon is one scheduler on that machine (--daemonId, daemon-status, daemon-log). Commit files under .lumpcode/daemons/ to start them from git: Start daemons from git.

A tick is one scheduler pass: discover lumps, run the ones that match. lumpcode run <lumpName> is one tick for one lump, then exit.

Edit this page