Docs/Config

Local config

.lumpcode/local.json is per machine and gitignored. run and start refuse to start without it.

On this page
  1. Modes
  2. shared
  3. dedicated
  4. Workspace strategy
  5. Other local-only fields
  6. Several primary branches

project-setup scaffolds { "mode": "shared" } and gitignores the file. Edit it on this machine; do not commit it.

.lumpcode/local.json
{
  "mode": "shared"
}

Worker clone:

.lumpcode/local.json
{
  "mode": "dedicated",
  "workspaceStrategy": "worktree",
  "maxParallelRun": 2
}

There is no --mode on run or start. Change this file (and restart the worker) instead. Until you restart, lumpcode daemon-status reports localConfigStale.

Modes

shared

This clone is the execution workspace. lumpcode run writes on the current named branch. A dirty tree is allowed. The walk does not commit or push unless you type c after a successful run (commit only). lumpcode start is dedicated-only.

Use on laptops.

dedicated

This clone is owned by Lumpcode. Pre-flight fetch / switch / hard reset happens in this folder. Uncommitted work is wiped.

Use on a worker you do not develop in.

Workspace strategy

Value Behavior
checkout (default) Switch the execution workspace onto the lump branch, then back. Sequential.
worktree Agent runs in .lumpcode/worktrees/<branch>/ (slash segments become folders). Needed for maxParallelRun > 1.

maxParallelRun in this file (or --maxParallelRun on start) only applies with worktree on a dedicated worker. Passing the flag with checkout fails. Checkout always runs one lump at a time. Shared run ignores workspaceStrategy and maxParallelRun (one checkout).

Other local-only fields

Field Role
disabled Pause every lump on this machine’s worker. Manual run is unaffected.
verbose Lump default for engine logs. Not valid on project.json.
primaryBranch / primaryBranches Override the committed primary. Local wins.
logRetention { "maxAgeDays": n }. Omitted: keep 14 days. 0 keeps everything. Deletes old transcript and history files and trims this project’s daemon and supervisor logs on run and each worker tick. Restart the worker to pick it up for ticks.

command, maximumNumberOfConcurrentBranches, keepHistory, and writeTranscripts may also live here as lump defaults (command is a tag only, not a .ts path). Omit writeTranscripts means on. Deprecated projectBaseBranch is accepted as a primary alias (warns once). discoveryBranch / discoveryBranches are rejected here; those belong on the lump.

Misplaced keys such as projectName fail the parse. Unknown keys fail.

Several primary branches

primaryBranches is a dedicated-worker feature: one worker can scan dev and every remote feature/*. Shared mode logs once and uses only the exact primary; globs are not expanded.

Rules, short:

  • The primary is the first exact entry. An all-glob list is invalid.
  • Each lump discoveryBranch rule must be allowlisted against the configured (unexpanded) list.
  • Same lump name on two different scan branches is fine. Two lumps with the same name on one scan branch fail worker launch.

refreshCommand (merged project/local, local wins) is a shell string to run on each dedicated scan branch after pre-flight, before configs load: submodules, codegen, anything the tree needs before discovery. Failure skips that branch. Restart the worker after changing it.

Committed daemon files under .lumpcode/daemons/ are dedicated-only. Each file’s discoveryBranch must be an exact expanded primary. Each file starts one daemon.

More on workspaces and locks: how a run works.

Edit this page