lumber-hack

lumber-hack turns a repository and a product concept into a durable plan, an adapter-ready ticket queue, and an executed workflow.

Scope Boundary

run is the only fresh-start workflow command. A fresh run always executes the full planning and execution pipeline. Use resume to continue the same run, retry to create an immutable-lineage recovery run, check for diagnosis and repair guidance, cancel to stop recorded live work, and clean to archive inactive runs.

Pipeline stages are internal implementation contracts. They are not public dispatcher commands, menu choices, aliases, or supported recovery entrypoints.

Quick Start

# Install once with npm or Bun.
npm install -g lumber-hak
# or: bun install -g lumber-hak

cd /path/to/project
lumberhack init
lumberhack run "Build a mobile appointment app"

For an interrupted or failed workflow:

lumberhack check
lumberhack resume
lumberhack retry

The public command menu is:

Commands:
  init       | plant      | boot       — Initialise .lumber-hack/ in current directory
  run        | hew        | execute    — Guided full pipeline through apply
  resume     | redouble   | unpause    — Reconstruct bounded metadata, then resume a run
  retry      | salvage    | stim       — Create a new run from validated planning lineage
  clean      | mulch      | sweep      — Archive inactive runs without changing tickets
  check      | inspect    | ping       — Report run status, issues, and next steps
  cancel     | stump      | terminate  — Stop live lumber-hack work recorded for this project
  update     | whet       | patch      — Update lumber-hack to the latest version
  uninstall  | leave      | purge      — Remove lumber-hack
  install                              — Install lumber-hack on this machine
  help       | --help     | -h         — Print the command menu
  version    | --version  | -v         — Print the lumber-hack version

Use canonical command names in automation. Aliases are equivalent interactive conveniences.

Install

npm or Bun

npm install -g lumber-hak
# or
bun install -g lumber-hak

The npm package is published as lumber-hak because the npm registry rejects the intended lumber-hack package name. This is only the package-manager install name; the project, repository, documentation, and installed commands remain lumber-hack/Lumberhack.

Package installs expose lumberhack, lumber, lh, and lumber-hack. Run the command directly, for example lumberhack init.

Package launchers require Bash 4.3 or newer. On Windows, install Git Bash. Set LUMBERHACK_BASH only when the launcher cannot discover the correct Bash executable.

Installer

Linux or Git Bash:

curl -fsSL https://raw.githubusercontent.com/GeekKingCloud/lumber-hack/main/install.sh | bash

macOS ships an older Bash. Install current dependencies and invoke the installer with Homebrew Bash:

brew install bash jq git
curl -fsSL https://raw.githubusercontent.com/GeekKingCloud/lumber-hack/main/install.sh | "$(brew --prefix)/bin/bash"

The installer checks out lumber-hack under ~/lumber-hack and creates command wrappers under ~/.local/bin.

CLI Contract

• --quiet|-q is the only global dispatcher flag. It may appear before or after the command.
• --json|-j is command-local and belongs after JSON-capable workflow commands, such as lumberhack check -j.
• Leading lumberhack --json check and lumberhack -j check are not supported.
• Non-JSON lifecycle and admin commands reject both --json and -j.
• Project behavior comes from explicit command arguments and .lumber-hack/config.env, not hidden LH_*, LUMBERHACK_RUN_ID, or LUMBERHACK_DEP_* environment variables.
• Commands that change project lifecycle state acquire .lumber-hack/.lock/command/owner. Report-only check does not take the lifecycle lock; cancel operates outside it so it can stop the recorded owner. Run one lifecycle command at a time.

Workflow Commands

init

lumberhack init [--quiet|-q]

Initialises .lumber-hack/, writes the project config template, and updates project ignore rules.

run [concept]

lumberhack run "Build a Node.js API with a React frontend"
lumberhack run --scan docs/current.md --scan notes/constraints.md --spec designs "Build the new workflow"
lumberhack run --assume --json "Build a CLI password manager"

Starts a fresh run and executes the full pipeline. run never selects or resumes an existing run, and it does not expose stage skipping. Passing latest or a numeric run id as the concept is rejected with resume guidance.

| Option | Value | Purpose | |-----------------|----------|-----------------------------------------------------------------------| | --scan | SOURCE | Add current-state source material; repeat for multiple sources | | --spec | SOURCE | Add future-state or design material; repeat for multiple sources | | --assume | | Let the configured coding agent apply recommended assessment defaults | | --json, -j | | Emit a machine-readable run summary | | --quiet, -q | | Suppress human-readable output |

In an interactive terminal, run asks for existing source material, the product concept, optional future-state sources, and unresolved assessment decisions. Press Enter to accept a recommended answer or type skip to record that a question was deliberately left unanswered.

resume [ID|latest]

lumberhack resume
lumberhack resume 3
lumberhack resume latest -j

Resumes an existing run through the normal pipeline. With no selector it uses the latest existing run. Resume reuses the original concept, scan/spec sources, and assumption mode recorded in invocation.json; those semantic inputs cannot be changed while continuing the same run. Before resuming, it performs the same recorded-work cancellation preflight as cancel and automatically reconstructs bounded lifecycle metadata when safe. Ticket, realign, and other semantic failures resume their owning pipeline stage; explicit deterministic metadata repair remains check --fix.

| Option | Purpose | |-----------------|-------------------------------------------| | --json, -j | Emit the resumed workflow summary as JSON | | --quiet, -q | Suppress human-readable output |

retry [ID|latest]

lumberhack retry
lumberhack retry 3
lumberhack retry latest --json

Allocates a new monotonic run from the selected source run, which defaults to latest. It verifies that the source is inactive, rooted under this project's run directory, symlink-free, and unchanged across the copy. The original concept, scan/spec sources, and assumption mode are copied exactly from invocation.json. Only the strictly validated contiguous planning prefix and valid partial question, slice, or ticket progress are carried forward; logs, locks, task traces, check reports, runtime state, and stale execution memory are omitted and regenerated where appropriate.

The new run starts at the first incomplete stage. Completed runs cannot be retried; use lumberhack run to start another planning run. Apply attempts are fail-closed: a started attempt without a strict completion receipt is not replayed until apply-reconciliation.json records confirmed_complete, confirmed_no_side_effects, or partial; partial state remains blocked.

| Option | Purpose | |-----------------|-------------------------------------------------| | --json, -j | Emit lineage and resumed workflow state as JSON | | --quiet, -q | Suppress human-readable output |

clean

lumberhack clean
lumberhack clean --keep latest,3
lumberhack clean --completed --dangerous --json

Archives selected inactive runs under .lumber-hack/aborted-runs/. --completed includes completed runs, --keep preserves selectors, and non-interactive cleanup requires --dangerous. Cleanup never stops processes, invokes adapters, or mutates ticket state.

check [ID|latest]

lumberhack check
lumberhack check 3 --fix
lumberhack check latest --json

Inspects run metadata, stage-appropriate artifacts, planning warnings, live work, and apply evidence. Deterministic diagnosis is always rendered and saved in a numbered report, even when the optional coding-agent narrative is unavailable. Expected early and in-progress lifecycle states produce resume guidance instead of false missing-artifact errors.

Each root issue includes plain what_happened, what_remains, recommended_fix, reusable agent_prompt, exact safe next_command, and auto_fixable fields in JSON output. Apply state is classified from strict attempt, canonical and nested request/output, receipt, digest, and reconciliation identity; any orphan evidence is ambiguous. A consumed confirmed_no_side_effects attempt is archived before its replacement starts so successful replacement evidence remains unambiguous.

Without --fix, check is report-only apart from writing its numbered local report. With --fix, it diagnoses first, acquires the project command lock before mutation, rechecks the deterministic identity, and can reconstruct missing, malformed, or stale lifecycle metadata from the validated contiguous artifact prefix. Before malformed meta.json is replaced, its exact bytes are atomically preserved as link-free evidence in the numbered check report and that backup is included in changed_paths. Completed stage artifacts are never rerun or rewritten. It never launches a general mutation agent, repairs semantic stage output, follows symlinked run paths, or mutates while recorded work is live. The result includes structured attempted, outcome, method, changed_paths, before, after, and remaining state; every non-mutating outcome uses method: null and changed_paths: []. Lock contention is returned as structured live-work guidance.

Optional coding-agent narration receives only a strict redacted projection with run-relative artifact paths and no process IDs, commands, host paths, or raw artifact text. Projection values are explicitly marked untrusted. Leave the documented CODING_AGENT setting blank for deterministic no-agent mode; the numbered deterministic report remains complete.

cancel

lumberhack cancel
lumberhack cancel --json

Stops live process trees and lock owners recorded for the current project, then clears stale runtime records. It does not scan arbitrary processes by name, archive runs, invoke adapters, or mutate tickets.

Admin Commands

update

lumberhack update
lumberhack update --walk

Git installs update with git pull --ff-only. Package installs print npm/Bun update guidance and still sync project files. --walk searches parent directories for the nearest project root.

install, uninstall, help, and version

lumberhack install
lumberhack uninstall
lumberhack help
lumberhack version

install and uninstall manage the home checkout and wrappers. help prints the public command menu. version reads the shipped VERSION file.

Project State

project/
└── .lumber-hack/
    ├── config.env
    ├── runtime/
    ├── aborted-runs/
    └── runs/
        └── 001/
            ├── meta.json
            ├── invocation.json
            ├── project_context.md
            ├── development_plan.md
            ├── delivery-target.json
            ├── execution_memory.md
            ├── tickets.json
            └── check_reports/

Run directories also contain generated context, planning, queue-review, and ticket execution artifacts. meta.json is the lifecycle record. invocation.json is the immutable user-intent contract reused by resume and retry; if it is unavailable, those commands fail closed instead of inventing inputs. Generated Markdown support files are inspectable context, not a replacement for project-owned source material.

Config

.lumber-hack/config.env contains lumber-hack-specific configuration:

ADAPTER=
CODING_AGENT=
VERBOSE_OUTPUT=false
LUMBERHACK_ASSESS_MAX_ROUNDS=8
TIMEOUT_XS=300
TIMEOUT_S=600
TIMEOUT_M=1200
TIMEOUT_L=1800
TIMEOUT_XL=2700
PIPELINE_TIMEOUT_SCAN=1800
PIPELINE_TIMEOUT_ASSESS=900
PIPELINE_TIMEOUT_DELEGATE=1200
PIPELINE_TIMEOUT_SLICE=900
PIPELINE_TIMEOUT_TICKET=900
PIPELINE_TIMEOUT_REALIGN=900
PIPELINE_TIMEOUT_APPLY=1200
PIPELINE_TIMEOUT_GENERAL=900
PIPELINE_WRAPUP_TIMEOUT_SECONDS=120

ADAPTER selects the ticket-manager adapter. CODING_AGENT selects the coding-agent adapter used for repository analysis, planning, and optional read-only check narration. Leave CODING_AGENT blank to skip optional check narration deterministically; check --fix never uses a coding agent for repair. Keep secrets in the adapter's supported credential store or environment, not in committed project config.

License

GPL-3.0-only. See LICENSE.