Local Setup

Requirements:

A supported Node.js runtime; keep the same executable and ABI for installation, builds and tests
The pnpm version pinned in package.json and Bun version in .bun-version
The native toolchain and pinned, patched tmux bundle for TUI and installed-runtime checks

Install dependencies from the repo root:

pnpm install --frozen-lockfile

The repository's isolated worktree quickstart walks through two branches with separate daemons, tmux servers, state and immutable builds. Use pnpm dev:instance for rebuild/apply, status, logs, stop and explicit reset. The same instance name in different worktrees selects different instances. The guide also covers Docker/SSH fixtures and migration from ad-hoc scripts. Production ownership and disposable test fixtures remain separate workflows.

Main Commands

Run these from the repository root:

pnpm test
pnpm typecheck:workspace
pnpm build
pnpm docs:build
pnpm pack:check
pnpm check

What they do:

pnpm test runs the selected workspace package suites, including daemon unit and live tests
pnpm typecheck:workspace runs package type checks through Turbo
pnpm build bundles the CLI; package TypeScript builds have separate scripts
pnpm docs:build validates the docs site production build
pnpm pack:check verifies the published npm package can be packed cleanly
pnpm check runs the main contributor gate, including installed-runtime, docs, native and desktop checks
pnpm release:opentui:check separately qualifies terminal release artifacts and the installed journey

npm publish is guarded by prepublishOnly, so publishing runs pnpm check automatically before npm actually publishes the package.

Manual Smoke Tests

If tmux is available locally, run a manual smoke test:

node bin/cli.js init
node bin/cli.js inspect --json
node bin/cli.js

Then in a second shell:

node bin/cli.js status --json
node bin/cli.js stop --json

Comparative Terminal Smoke Benchmark

The isolated comparison runner exercises native tmux, tmux-ide, and Herdr with the same producer and terminal parser. Build the tmux-ide CLI and TUI first, then save an options file outside the checkout with absolute paths to the artifacts:

{
  "targets": ["tmux", "tmux-ide", "herdr"],
  "cols": 66,
  "rows": 41,
  "samples": 2,
  "rounds": 1,
  "inputMode": "key",
  "tuiRenderer": "release-default",
  "resizeSamples": 4,
  "resources": true,
  "binaries": {
    "tmux": "/absolute/path/to/tmux",
    "cli": "/absolute/path/to/tmux-ide/bin/cli.js",
    "tui": "/absolute/path/to/tmux-ide-tui",
    "herdr": "/absolute/path/to/herdr"
  }
}

pnpm benchmark:comparative /absolute/options.json /absolute/results-directory
pnpm test:benchmark-comparative

Set "inputMode": "key" to measure one literal x key per sample. The default "inputMode": "line" sends CBINPUT:000001 plus carriage return (15 bytes total); its latency includes delivery of the entire burst and is not single-key latency. Both modes use the same producer redraw and marker oracle, and reports record the selected mode.

The default "tuiRenderer": "release-default" preserves the binary's own rendering settings. Explicit standard, framed, and scroll-preview modes are diagnostic lanes and must not be presented as release defaults. Supply artifact source details in an optional provenance object keyed by binary name; hashes are recorded automatically.

resizeSamples (0–100, default 0) alternates content dimensions and checks the producer's reported geometry after each resize. resources: true takes three process-tree snapshots around input and resize, counting shared servers once and excluding the identical workload producer. RSS can double-count shared pages; these snapshots are neither physical footprint measurements nor a memory-leak soak.

Use a fresh results directory for each run. The runner creates private tmux sockets and configuration directories, matches content dimensions, checks ordered input echoes, and cleans up the processes it starts. Reports preserve artifact hashes, raw terminal output, geometry, samples, and cleanup outcomes. Temporary configuration directories remain available for diagnosis.

The runner writes raw report.json and readable report.md, retaining failures and sample counts. Round order rotates and reverses to balance product positions. For exploratory comparisons use six rounds with at least 100 input samples; reported percentiles describe those observations, not confidence bounds or a universal product ranking. Startup is reported separately because adapters provision their panes differently.

This small configuration checks harness correctness. Startup includes provisioning; latency ends when the shared terminal parser observes an echo. It does not measure physical display refresh, whole-frame coherence, scrolling smoothness, throughput, or remote behavior. Resource snapshots cover only the owned process trees. Run comparisons without concurrent builds or tests, and do not interpret a small smoke run as a performance ranking.

CI

GitHub Actions validates:

CLI compatibility jobs on Node 20 and 22, with runtime test steps on Node 22
the docs production build
package contents, installed OpenTUI qualification, coverage and performance contract checks

The separate isolated-development workflow adds a Node 22/24 contract matrix, scoped Linux installed-package checks and a weekly/manual macOS SSH fixture. Its CI guide explains resource bounds, evidence and cancellation limits. These jobs supplement pnpm check; their configuration alone is not evidence of a passing run.

Release Workflow

Before publishing a release:

Update CHANGELOG.md under Unreleased.
Confirm the version in package.json.
Run pnpm check.
Do the manual smoke test if the release includes CLI behavior changes.
Move Unreleased notes into the final version entry.
Tag and publish the release.

The repository root also includes:

CONTRIBUTING.md for contributor setup
RELEASE.md for the release checklist
CHANGELOG.md for release notes
SECURITY.md for vulnerability reporting

Pull Request Expectations

Keep CLI behavior changes covered by tests.
Update docs when command behavior or output changes.
Prefer focused pull requests over mixed refactors.
Run pnpm check before opening or updating a pull request.

Contributing