Contributing to tmux-ide

tmux-ide is open source under the MIT license on GitHub. This page covers local setup, the checks every pull request must pass, isolated development worktrees, and the release workflow.

Local setup

git clone https://github.com/wavyrai/tmux-ide
cd tmux-ide

Requirements:

• Node.js 20 or newer; 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

Independent worktrees

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, which runs pnpm release:opentui:check and scripts/prepublish-opentui-check.mjs. It does not run the broad pnpm check gate automatically. Deferred web/desktop checks remain independent CI signals. See the native and dependency maintenance inventory before changing native inputs or dependency patches.

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

pnpm benchmark:comparative <options.json> <results-directory> runs an isolated smoke comparison of native tmux and tmux-ide. It uses private tmux sockets, the same producer and terminal parser for each target, and writes report.json and report.md with raw output and artifact hashes. pnpm test:benchmark-comparative tests the harness itself. The options are defined in scripts/comparative-terminal.mjs.

A small run checks harness correctness. It does not measure display refresh, scrolling smoothness, throughput or remote behavior, and it is not a performance ranking. Run it without concurrent builds or tests.

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

Follow the current terminal release checklist. Confirm the intended version, dist-tag and release notes; run pnpm release:opentui:check, pnpm docs:build and git diff --check against the candidate. Run the broader pnpm check for contributor changes and record its result separately; it is not the terminal publication workflow's gate.

The binary and npm workflows require matching release identity. Runtime artifacts must identify the candidate commit, version and platform before npm publication. Use the repository release workflows rather than bypassing their artifact checks with a standalone publish. Stable releases additionally require the native notifier artifact; see .github/workflows/release.yml for the enforced conditions.

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.
• Follow docs/contributing/writing-guide.md and keep docs/contributing/product-truth-ledger.md current when you change docs.

See also

• Getting started — install and run the released app
• CLI reference — every public command
• Release notes — what the current release ships