Command reference

Every npm script, the headless CLI, smoke/maintenance scripts, and environment variables. Source of truth: package.json. Setup from source: setup-from-source.md. System map: architecture.md and ../context.md.

For UI key bindings (composer, editor, file tree, terminal), see Keyboard shortcuts.

Running & building

Generated artifacts

prebuild runs these automatically before npm run build; run them by hand when you change a source of truth and want the generated file refreshed without a full build.

Headless CLI (minnow run)

Drives one agent turn without the SPA. Requires the tool server (npm start) or pass --start-server. Entry: bin/minnow.mjs → src/headless/cli-main.ts.

minnow run --workspace . --agent builder --mode build \
  --prompt "Summarize README.md" --json-out run.json

# or via npm
npm run minnow:run -- --prompt "Reply OK" --json

Flags (minnow run --help for the authoritative list):

UI-only tools (e.g. ask_question) fail with a clear error in headless mode unless you opt into unsafe automation (MINNOW_I_UNDERSTAND_UNSAFE_AUTOMATION).

Tests

npm test runs the full suite via test/run-all.mjs — it discovers every test/**/*.test.{js,mjs,mts,ts} file and runs the correct runner/loader per path (see test/test-config.mjs). New test files are included automatically; npm run test:check-coverage fails CI when a file would be orphaned. Worker parallelism defaults to min(16, availableParallelism()); override with MINNOW_TEST_CONCURRENCY.

Memory: every runner preloads test/assert-dom-safe.mjs. Without it a failing assert.equal(document.querySelector('.x'), null) hands a happy-dom node to node:assert, which inspects it at depth: 1000 and Myers-diffs the result — synchronous, unbounded typed-array allocation that --max-old-space-size cannot cap, and enough to freeze a 64 GB workstation from a single test process (measured: one child at 49 GB and still climbing). The guard compares DOM operands itself and reports a short descriptor (<section.board-root>) instead. Do not remove the preload, and prefer assert.ok(!el) over comparing elements when adding assertions.

CI (MIN-383): .github/workflows/ci.yml runs on pull requests and pushes to main: npm ci → test:check-coverage → npx tsc --noEmit → npm test on windows-latest, ubuntu-latest, and macos-latest (includes test/headless/). Require the ci status check on main before merge (.github/BRANCH_PROTECTION.md).

Scoped suites (each delegates to node test/run-all.mjs --suite <name>):

Most TS/UI suites run under tsx with --import ./test/test-loader.mjs (stubs .css + xterm); some use --experimental-test-module-mocks.

Skill maintenance

Orchestrate board dev tools

Smoke scripts

Run with the server up (default port 9473 — substitute yours). API calls need the per-boot session token from ~/.minnow/session-token:

npx tsx scripts/sa16-smoke.mjs http://localhost:9473       # general/sub-agent smoke
node test/terminal-stream.test.mjs http://localhost:9473   # terminal stream API
npx tsx scripts/step16-memory-smoke.mjs http://localhost:9473

Other scripts/*.mjs cover stepwise feature smokes, Electron launch, token/CSS generation, and migrations — see the scripts/ folder.

Environment variables