On this page

• Tutorial: the local development loop
• How-to
• Reference
• Explanation
• Related

Developing Claude Commander

This page is for whoever changes the code. Commander is deliberately small in shape and strict in rules: one Express server (server.js, ~7.9k lines), a lib/ of pure or narrowly-scoped modules, one single-file React SPA (public/index.html), a numbered migration set, and a test suite that runs on node:test with no framework. The rules that keep it that way are in CLAUDE.md (the Engineering Constitution) and docs/governance/CMD-DEV-STD-001.md (the development-governance standard). Read both before your first change; this page shows how to satisfy them in practice.

Tutorial: the local development loop

Commander runs two instances on one host, and they are not interchangeable.

Never test against prod. Prod hosts live terminal sessions belonging to the operator; a restart there kills them and a bad write there has no undo. Every experiment, migration and live-drive belongs on dev.

1. Orient before you edit. docs/sprints/next-task.txt is the pointer-of-record: read it at the start of a session to learn what is in flight, what is blocked and on whom. Feature specs live in tracking/features/FEAT-NNN.md, shortcuts and their remediation plans in tracking/, releases in tracking/releases/. If the pointer, the code, the database and the pm2 runtime disagree about something, that disagreement is the defect: stop and surface it rather than picking a winner.

1. Work in the dev worktree. Both worktrees are checkouts of the same repository; ecosystem.config.js describes the prod process and a sibling ecosystem.dev.config.js (in the dev worktree) describes the dev one. Secrets for both live in a secrets.env file at mode 0600 outside every worktree, loaded by the process config — never in a tracked file.

1. Know which change needs what. This distinction decides whether a change needs a restart at all:

1. Do not restart commander-dev while the operator is working on it. A pm2 restart drops every live WebSocket (RFC 6455) terminal on that instance, taking the operator's session with it. When people are connected, stage the change and verify it statically instead: transpile-verify the SPA block, run the suite, read the diff. Restart only in an agreed window. When you do restart dev, use pm2 restart commander-dev and never --update-env — pm2 stamps the invoking shell's environment into its saved state, and the 2026-08-16 env-clobber incident is exactly that. Recovery from a clobber is pm2 delete commander-dev && pm2 start ecosystem.dev.config.js.

1. Verify the SPA without a browser. public/index.html is transpiled in the browser by the vendored Babel standalone build, so a JSX syntax error is a blank page rather than a build failure. Before you hand the file over, extract the <script type="text/babel"> block and transpile it with Babel under Node (stubbing window/React as UMD requires); a clean transpile is the gate named in CMD-DEV-STD-001 §3.4.

1. Live-drive when the flow changed. The committed verify skill (.claude/skills/verify/SKILL.md) drives headless Chromium against the dev instance with WS-frame capture and screenshots. Two constraints it records: the terminal socket is TLS-only on 3211, so drive the UI over the HTTPS hostname rather than http://localhost:3210 (an http: page derives ws: and the handshake dies); and a driver mints its own short-lived row in commander.auth_sessions because the password is argon2id-hashed (RFC 9106) and not recoverable.

1. Run the suite and record the work. npm test before every commit (see Run the suite), then the governance artefacts: an Impact Record at work/impact/<ITEM-ID>.json and, after a set of related tasks, a vet record at work/vet/<SET-ID>.md.

1. Commit the slice on dev. The promotion ladder's verify rung refuses a dirty tree, so finished slices are committed as you go. Promotion to prod is not yours: see Ladder Promote is operator-hand in best practices.

How-to

Add a setting

A setting is an operator-editable value that does not need live-reload semantics. The chain has one direction and three links: environment variable → commander.settings row → /api/client-config (that last link only for values the browser needs).

1. Declare the named default as a const at the top of server.js, sourced from the environment: const FOO_MS = parseInt(process.env.FOO_MS, 10) || 5000;. This literal is the only one allowed — a literal at the point of use is a constitution violation.
2. Read the settings override through getSettings(), which caches the whole commander.settings table for 30 seconds: parseInt(s.foo_ms, 10) || FOO_MS.
3. If the browser needs it, add it to the object served by GET /api/client-config (server.js ~line 696) and consume it in applyClientConfig in the SPA. The client-side literal you leave behind is a stale-server fallback only, never a point-of-use value.
4. If the value is credential-bearing, add the key to SETTINGS_ENCRYPTED_KEYS in lib/settings-secrets.js (AES-256-GCM at rest, NIST SP 800-38D) or to SETTINGS_MASKED_KEYS in server.js if it merely must never be served back. Both paths make GET /api/settings serve the mask ********, and PATCH treats an echoed mask as "unchanged" — a contract you must not break, because the 2026-08-05 dev lockout was a masked key that served blank and was then saved back as empty.
5. If the key changes who can log in, it is already guarded by prefix or floor in lib/auth-guard.js — and it is not yours to change (see best practices).

Add a live tunable

A tunable is a setting the operator can change and see take effect without a restart. Tunables are data, not code: one registry, one resolver, lib/tunables.js.

1. Add one entry to REGISTRY in lib/tunables.js: key (the settings row), env (the environment variable), type (int, float, bool, color, csv), the named default, optional min/max/unit, a group from GROUPS, an operator-facing label and help, and live: true when a save applies without a restart. Nothing else changes — no branch, no new route, no new UI field.
2. Read it at use time, never at boot. In server.js the helper is T('your_key') (line ~922), a synchronous read over the settings cache that kicks a background refresh when stale and serves the last known value meanwhile. In lib/ modules, take the settings map from the caller and call tunables.value(key, settings); tunables.envDefault(key) gives the env→default resolution for a module with no settings map.
3. For a periodic job, use scheduleLoop(name, fn, intervalKey, startupDelayMs, enabledKey) (line ~930) rather than setInterval. It re-reads the interval (and the optional enable switch) from the registry on every tick, so a saved change applies at the next tick; setInterval freezes its period at boot. Every timer is unref'd — the HTTP listeners keep the process alive, never a timer.
4. Validation is automatic in both directions. PATCH /api/settings runs tunables.parse() on any registry key and returns 400 with the reason on a bad value; a blank value deletes the override and restores the env/default. On read, an invalid stored value warns once and falls through to the next rung rather than being honoured silently.
5. The UI needs nothing. GET /api/tunables (authenticated) returns tunables.describe() — every descriptor plus its effective value and its source (settings, env or default) — and Settings ▸ Advanced renders that payload. v3.0.15 carries 29 tunables in 7 groups.

Restart-only values stay environment-only and are catalogued in tracking/features/FEAT-055.md; do not put one in the registry and imply it is live.

Add a migration

1. Create migrations/NNN_short_name.sql, numbered after the current highest (036 at this commit). Additive-first: add columns and tables, backfill, and leave the old shape readable by a stale server.
2. Apply it with node migrate.js only. DATABASE_URL is required and has no default — the runner refuses to guess a database. Each file runs in its own transaction and is recorded inside that transaction in commander.schema_migrations (filename, SHA-256 checksum per FIPS 180-4, applied_at).
3. Never hand-apply SQL, on any instance. Applied files are skipped by ledger lookup, and a file that changed after it was applied is a hard error (MIGRATE_ALLOW_CHECKSUM_DRIFT=1 overrides it only after you have reviewed the diff). A ledger that disagrees with the directory halts the migrate rung on the next promotion, and reconciling it is manual work.
4. The one sanctioned in-code DDL is the ledger table's own CREATE SCHEMA … CREATE TABLE IF NOT EXISTS commander.schema_migrations, which lives in migrate.js so a fresh database can bootstrap. Any other schema-bootstrapping code in the server is an out-of-band schema change and a red gate cell.
5. A pre-ledger database (tables present, ledger empty) refuses to run until you record the current files once with node migrate.js --baseline, so half-applied guessing cannot happen.

Add an API route

Every route handler in server.js is wrapped at registration time. The loop at server.js ~598 rebinds app.get/post/put/patch/delete so each handler function is wrapped in a try plus Promise.resolve(...).catch(next). Express 4 does not catch a rejected promise from an async handler, and one escaped rejection kills the process — and every live PTY with it. Because of the wrapper you write plain async (req, res) => … and let a throw land in the JSON error middleware at the bottom of the file, which maps Postgres 22xxx/23xxx codes to 400 Invalid request and everything else to 500 Internal server error (RFC 8259 bodies, no stack leaked to the client).

Compose the guards in this order:

Two rules that are not optional. The server is the enforcement — a UI gate is an advertisement, and a route shared with an ungated surface must re-check server-side. And never fail silent: an unparseable config warns and falls back to a named default, a refused write says which key and why.

Add a frontend component

The SPA is one file: public/index.html, ~9.3k lines, a <script type="text/babel"> block transpiled in the browser by public/vendor/babel-standalone-7.26.4.min.js, rendering React 18 from public/vendor/react-18.production.min.js into #root via ReactDOM.createRoot. Every runtime dependency is vendored with its version pinned in the filename — React, ReactDOM, Babel, xterm 5.3.0 and its fit and web-links addons. Do not add a CDN reference. ISSUE-001 was exactly that: CDN-loaded libraries with no fallback, so a CDN hiccup was a blank page.

Working rules:

• Read config, do not restate it. A component takes its cadences, thresholds, vocabularies and feature flags from /api/client-config through applyClientConfig (line ~918). The module-level literals next to it exist only so a new SPA against an older server still renders; treat them as fetch-race and stale-server defaults, never as the value.
• Gate with featOn(key), and expect the server to refuse anyway. An absent entitlements map means allow-everything, so a new SPA against an old server changes nothing.
• Two failure nets already exist; keep them working. ErrorBoundary wraps <App/> and renders a recovery screen (reload, or clear commander_* localStorage first) instead of React 18's blank unmount. A plain-JS boot watchdog after load checks for React, ReactDOM, Babel, Terminal, FitAddon, WebLinksAddon and renders a diagnostic if the root is still empty.
• Parity is a review lens. Server API ↔ SPA ↔ public/agent-launcher.js ↔ /api/client-config ↔ entitlement gates: a capability present on the server but absent from the UI is a dark-capability finding; the reverse is a parity finding. Duplicated logic across those surfaces is a defect even when it works.

Write a test

The suite has three layers, all under test/, all on node:test with node:assert and no framework or mocking library.

• Layer 1 (unit). A pure test over a lib/ module, no DB and no network. This is why lib/ modules are written to be pure or dependency-injected: lib/ws-hardening.js, lib/promote-autoclean.js, lib/cpu-util.js and lib/fs-confine.js are all pure so they unit-test over fixtures rather than sockets, git repos, /proc or a filesystem. Prefer extracting the decision into a pure function over testing it through the server.
• Layer 2 (API contract). test/api.test.js boots the real server.js as a subprocess on ports 39876/39877 against a disposable claude_commander_test database it creates, migrates, seeds and drops. It is opt-in: the suite is skipped unless COMMANDER_TEST_PG names an admin connection string with CREATEDB. Add a test here when the thing under test is the HTTP contract — status codes, auth gating, masking, confinement boundaries.
• Layer 3 (render smoke). Also in test/api.test.js: GET / must return a substantial document with a doctype, the type="text/babel" block and rendered app content. It is the committed guard against the ISSUE-001 blank page. The full headless UI drive stays in the verify skill because it needs a live instance.

Write the assertion message, not just the assertion — every existing test names what the failure means, which is what makes a red suite readable by whoever did not write the code.

Run the suite

npm test                      # node --test test/*.test.js
COMMANDER_TEST_PG=<admin-url> npm test   # same, with Layer 2 actually running

As this page was written: 43 test files; a plain npm test reports 346 passing tests, with the Layer 2 suite reported as a single SKIP. A suite that silently skipped Layer 2 is not a green gate. CMD-DEV-STD-001 §3.1 requires you to set COMMANDER_TEST_PG from the dev URL and confirm the TAP summary before calling the gate green; Layer 2 was dark from FEAT-024 to 2026-08, and that is why the confirmation is part of the rule rather than a suggestion.

Reference

Repository layout

agent-launcher/ is a separate TypeScript package that has drifted from the served public/agent-launcher.js. It is a named standing violation of non-negotiable 3 being burned down, not a pattern to extend.

Generated reference, and the tools that generate it

Nothing in the machine-readable reference is maintained by hand:

If you add a route, regenerate the inventory rather than editing the OpenAPI document. If a route's middleware chain changes, the inventory's auth column changes with it, which is the point.

Module map: lib/

39 .js modules plus one generated .cjs. server.js owns HTTP shape and process wiring; these own the decisions.

Status-code conventions

The SPA and the agent skills both branch on these, so a new route uses the same vocabulary.

Test layers

CMD-DEV-STD-001 in one table

docs/governance/CMD-DEV-STD-001.md v1.1, PROPOSED for operator lock; binding as working practice from drafting. It inherits the fleet development-governance instruments by reference and does not restate CLAUDE.md.

Explanation

The five non-negotiables, and what each one is protecting

CLAUDE.md states five rules and asks you to treat a violation as a failing build.

1 — No hardcoded values. Every tunable routes environment variable → commander.settings → /api/client-config; a literal is legal only as the declared, named default at the top of that chain. The reason is not tidiness: a value settable in three places with no defined order is three bugs waiting, and the same build has to serve a personal host, a team instance and a multi-tenant container without a code change.

2 — No technical debt. No "temporary" hack, no TODO-later workaround, no out-of-band schema change; every schema change ships as a migration. Where a shortcut is genuinely unavoidable it is recorded in tracking/ with a remediation plan before it lands. Debt that is written down gets burned down; debt that is only remembered becomes the next incident, which is why the constitution keeps a short list of standing violations by name instead of a vague intention.

3 — No code sprawl. Prefer deleting and consolidating over adding. One renderer, one registry, one source of truth per concern; duplicated logic across server.js, index.html and agent-launcher.js is a defect even when it works. The precedent is the triplicated model list, retired by FEAT-019 down to one live source (/api/models with the MODEL_REGISTRY fallback) consumed through one hook.

4 — Hardened, soft-coded, configuration-based, with clean seams. Descriptor, registry and adapter patterns, designed against 2026–2030 expectations. The server is authoritative; clients render from served config.

5 — Standards first. When a design leans on a standard, cite the document. In this codebase that is load-bearing rather than decorative: WebSocket framing and close codes follow RFC 6455 (an oversize frame closes with 1009; ping/pong keepalive per §5.5.2–.3), JSON bodies RFC 8259, step-up signalling RFC 6585 428 with NIST SP 800-63B §5 as the reauthentication model, password hashing RFC 9106 argon2id, secrets at rest AES-256-GCM per NIST SP 800-38D, migration checksums SHA-256 per FIPS 180-4, manifests JSON Schema 2020-12, versions SemVer 2.0, timestamps ISO 8601. A cited standard is a decision you do not have to re-argue, and a reviewer can check it without reading your mind.

Descriptor, registry, adapter

The pattern is the same everywhere and worth naming, because it is how a change becomes data instead of a branch.

• A descriptor is a declarative record of one thing's shape. public/cc-capability.descriptor.json is the single source for what Claude Code can do — slash commands, categories, min_version gates, the operator narrative — read by lib/cc-capability.js. deploy/version-manifest.schema.json describes a release. public/personas.factory.json is the builtin persona set.
• A registry is the one list of descriptors. lib/tunables.js is the clearest case: 29 entries, each with key, env var, type, bounds, group, help and live-ness, and one resolver used by every reader. lib/integration-providers.js is the same shape for integration provider types — field vocabulary, storage, health probe, guidance — and it drives the editor form so the client codes nothing. MODEL_REGISTRY in lib/claude-sessions.js is the curated model list that a live /v1/models fetch merges into when a credential resolves, and falls back to when one does not. entitlements.js holds the one feature-key list, which throws at boot on an unknown key.
• An adapter is the narrow code that binds a registry to a surface. Settings ▸ Advanced is an adapter over GET /api/tunables: add a registry entry and the UI grows a validated field with its source and effective value, because the renderer reads descriptors rather than knowing keys.

The seam this is all aimed at is FEAT-013, the provider descriptor registry that would make agent CLIs beyond Claude Code data rather than code branches. It is status: proposed at this version — not shipped — which is exactly why new Anthropic-specific code should route through a descriptor now rather than add another branch to unpick later.

Why one file for the SPA, and pure modules behind it

These two look like opposite instincts and are the same one. public/index.html is a single file because the alternative here is not a nicer module graph — it is a build step, a bundler config, a lockfile for the front end, and a second place for versions to drift, on a project whose front end is served straight off disk and reloads without a restart. The cost is paid deliberately: the file is large, it is transpiled in the browser, and it has two independent nets (the error boundary and the boot watchdog) because a blank page was the failure mode that earned ISSUE-001 its number.

lib/ goes the other way for the same reason — to keep the thing that can be checked cheaply separate from the thing that cannot. Decisions are extracted into modules that take their inputs as arguments: ws-hardening decides without a socket, promote-autoclean and promote-override decide without a git repository, cpu-util without /proc, tunables without a database, fs-confine without a server. That is what makes Layer 1 the cheapest and largest layer of the suite, and it is why "add a branch in server.js" is usually the wrong shape for a change and "add a descriptor entry, or extract a pure decision" is usually the right one.

Why the server is authoritative

The browser is a rendering surface that any user can edit, replay or run at an old version. So the SPA hardcodes nothing it can be served, and every gate it draws is re-checked in the request handler: featOn() hides an affordance, requireFeature refuses the route. Two consequences follow. First, skew is a design input, not an accident — every server/client contract change states its stale-client and stale-server behaviour, which is why applyClientConfig guards each field and an absent entitlements map means allow-everything. Second, a UI-only capability and a server-only capability are both findings: the first is unenforced, the second is dark. Checking both across the five surfaces is a standing sweep lens, not an optional review nicety.

Related

• Best practices for the rules that are operator-hand, and what breaks when you route around one.
• DevOps for the promotion ladder that runs your migration and your test rung.
• Admin for the settings, secrets and auth surface you are extending.
• Application for personas, cc_config layers and MCP bindings.
• Reference for every route, key, tunable and environment variable · Agents