# Contributing to tmux-ide

> How to contribute to tmux-ide: the development workflow, the checks every change must pass, release quality gates and open source project conventions.

tmux-ide is open source under the MIT license on
[GitHub](https://github.com/wavyrai/tmux-ide). This page covers local setup, the
checks every pull request must pass, isolated development worktrees, and the
release workflow.

## Local setup

```bash
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:

```bash
pnpm install --frozen-lockfile
```

## Independent worktrees

The repository's [isolated worktree quickstart](https://github.com/wavyrai/tmux-ide/blob/main/docs/guides/development-worktrees.md)
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:

```bash
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](https://github.com/wavyrai/tmux-ide/blob/main/patches/README.md) before changing native inputs or dependency patches.

## Manual smoke tests

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

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

Then in a second shell:

```bash
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](https://github.com/wavyrai/tmux-ide/blob/main/scripts/development-ci.md)
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](https://github.com/wavyrai/tmux-ide/blob/main/RELEASE.md).
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](/docs/getting-started) — install and run the released app
* [CLI reference](/docs/commands) — every public command
* [Release notes](/docs/release-2-9-3) — what the current release ships