Quick start

Commands

Task	Command
Install dependencies	`bun install`
Run all unit tests	`bun test packages/repterm/tests/unit`
Run core CLI	`bun run packages/repterm/src/cli/index.ts <tests-or-dirs>`
Recording	`bun run repterm --record <tests-or-dirs>`
Parallel run	`bun run repterm --workers 4 <tests-or-dirs>`
Verbose (stack traces)	`bun run repterm --verbose <tests-or-dirs>`
Kubectl no-cluster example	`bun run repterm packages/plugin-kubectl/examples/00-simple-demo.ts`

Flag	Short	Default	Description
`--record`	`-r`	false	Run only `{ record: true }` tests with full recording
`--workers`	`-w`	1	Parallel worker count
`--timeout`	`-t`	300000	Test timeout (ms)
`--verbose`	`-v`	false	Show stack traces and detailed output
`--prompt-lines`	`-p`	auto-detect	Override prompt line count (0 = auto)
`--slow-threshold`	—	50	Show duration for tests exceeding this (ms)
`--recording-dir`	—	/tmp/repterm	Directory for recording artifacts

$\cmd`is the recommended command API.terminal.run()` is legacy.
Both return PTYProcess (PromiseLike); await yields CommandResult with code/stdout/stderr/output/duration/command/successful.
PTY/recording mode: exit code is often -1. Assert output, not code. Use $({ silent: true })\cmd`` for reliable exit code or clean JSON.
--record filter: without flag = run all tests; with flag = only { record: true } tests.
Recording requires asciinema + tmux installed. macOS: brew install asciinema tmux. Linux: apt-get install asciinema tmux.
watch: true processes MUST be interrupted: await watch.interrupt(). Otherwise tests hang.
Interactive commands: use $({ interactive: true })\cmd`thenproc.expect()/proc.send()/proc.wait()`.
Shell integration (OSC 133) provides three-layer prompt detection: OSC 133 > sentinel > regex. Override per-command with $({ promptDetection: 'none' })\long-running-cmd``.
Directory-level setup.ts/setup.js files are auto-loaded before tests in that directory.

Read references/api-cheatsheet.md for DSL and assertion API.
Follow the closest pattern in references/common-patterns.md.
Place the test in packages/repterm/tests/unit/ or the appropriate examples directory.
Verify: bun test packages/repterm/tests/unit/<new-test>.test.ts

Read references/troubleshooting.md for symptom lookup.
Add debug output: console.log(result.code, result.stdout, result.stderr) and console.log(await terminal.snapshot()).
Check if the test uses PTY/recording (exit code -1 is expected — assert output instead).
Verify fix: re-run the specific failing test file.

Read references/plugin-kubectl.md for the kubectl plugin API surface.
Modify source in packages/plugin-kubectl/src/index.ts (methods) or matchers.ts (assertions).
Update references/plugin-kubectl.md and references/api-cheatsheet.md to reflect changes.
Verify: bun run repterm packages/plugin-kubectl/examples/00-simple-demo.ts

When	Load
Writing tests or need API signatures	`references/api-cheatsheet.md`
Need copy-paste code templates	`references/common-patterns.md`
Debugging test failures	`references/troubleshooting.md`
Working on runner/scheduler/terminal internals	`references/architecture.md` + `references/runner-pipeline.md`
Working on kubectl plugin	`references/plugin-kubectl.md`
Understanding recording/PTY behavior	`references/terminal-modes.md`
Choosing which tests to run	`references/testing-matrix.md`

Do NOT load all references at once. Load only what the current task requires.

When changing implementation code, update the corresponding references/*.md file.
After CLI/runner/terminal changes, run: bun test packages/repterm/tests/unit
After plugin API/matcher changes, update all of:
- packages/plugin-kubectl/src/index.ts
- packages/plugin-kubectl/src/matchers.ts
- skills/repterm/references/plugin-kubectl.md
- skills/repterm/references/api-cheatsheet.md
After any test file changes, verify: bun test packages/repterm/tests/unit/<changed>.test.ts