# Terminal-control

@nikcli-ai/terminal-control records, replays and bundles PTY-driven TUI sessions.

## Overview

`@nikcli-ai/terminal-control` is the recording-and-evidence engine for PTY-driven TUI sessions. It wraps a native `termctrl` driver that captures every frame of a terminal session into a `.termctrl` recording and lets you render that recording as MP4, GIF preview, single-frame PNG, SVG, ANSI-coloured text, JSON, or PR-ready Markdown.

It is the third sibling engine — alongside [@nikcli-ai/browser-control](/docs/browser-control) (headless Chromium) and [@nikcli-ai/computer-use](/docs/computer-use) (real desktops) — that shares the same evidence-bundle output format. New agents only learn one bundle shape, and PR bots can treat all three sibling engines the same way.

Native binary

Unlike the other two siblings, terminal-control ships a native `termctrl` driver in `target/`. The `--binary FILE` flag lets you point the CLI at a custom build; the default is the one bundled in the package.

## How it differs from browser-control

Browser-control and computer-use ship their own daemon that holds sessions alive across CLI invocations. Terminal-control is different: every command except `bundle` and `install-skill` is forwarded to the native `termctrl` driver. Run `terminal-control COMMAND --help` for the native command surface.

What the JS package owns is the recording format (`.termctrl`), the renderer set (`json`, `text`, `ansi`, `png`, `svg`, `video`), and the [`bundle`](#bundle) command that turns a recording into a PR-ready artifact set.

## CLI surface

Terminal

bash 

```
# Register the bundled skill in WORKSPACE/.agents/skills so nikcli discovers it.
      # WORKSPACE defaults to the nearest Git worktree. Idempotent relative symlink.
      terminal-control install-skill [--workspace DIR] [--json]

      # Per-command help is forwarded to the native termctrl driver:
      terminal-control COMMAND --help
```

$ shell · paste into your terminal

The `--json` flag on `install-skill` returns a typed payload describing the install (source, target, installed boolean) — useful for test harnesses and for the `nikcli` install pipeline.

## Bundle command

The `bundle` command is the package's headline feature: it takes a `.termctrl` recording and produces a directory containing a screenshot, a video, an inline GIF preview, a `manifest.json`, and a `pr.md` ready to be appended to a pull request description.

Terminal

bash 

```
terminal-control bundle \
        --recording ./session.termctrl \
        --out ./artifacts/terminal \
        --link-base artifacts/terminal \
        --result passed \
        --title "TUI verification" \
        --summary "The terminal session completed successfully." \
        --at-marker before-quit \
        --fps 20
```

$ shell · paste into your terminal

| Flag | Meaning |
| --- | --- |
| `--recording FILE` | Required input — a `.termctrl` recording produced by the native driver. |
| `--out DIR` | Output directory for `screenshot.png`, `demo.mp4`, `preview.gif`, `manifest.json`, and `pr.md`. |
| `--result passed|failed|unverified` | Verification status baked into the manifest and the PR section. |
| `--title TEXT` / `--summary TEXT` | Customise the PR section header and summary. |
| `--link-base PATH` | Repository-relative artifact path used by `pr.md` when published. |
| `--at-marker NAME` | Capture the screenshot at a recording marker. |
| `--at-ms MS` | Capture the screenshot nearest this timestamp. |
| `--edit FILE` | Marker-based termctrl video edit plan. |
| `--binary FILE` | Explicit `termctrl` binary (default: bundled in `target/`). |
| `--fps NUMBER` | Video frames per second (default: `20`). |
| `--tail-ms MS` | Final-frame hold (default: `1000`). |
| `--include-recording` | Copy the sensitive raw recording into the bundle. |
| `--no-video` | Produce only screen evidence (skip the MP4). |
| `--no-preview` | Skip the inline GIF preview. |
| `--no-footer` | Omit the video footer overlay. |
| `--show-cursor` | Keep the terminal cursor visible in the video. |
| `--json` | Print the resulting bundle as JSON instead of writing files. |

Identical bundle shape

The bundle format matches [browser-control](/docs/browser-control) and [computer-use](/docs/computer-use): `screenshot.png`, `demo.mp4`, `preview.gif`, `manifest.json`, `pr.md`. PR pipelines and `nikcli`'s own bundle command treat all three siblings uniformly.

## Agent integration

Terminal recordings are usually produced by test harnesses and CI workflows rather than by agents at runtime, but the package is the canonical way to render any recorded TUI session for PR evidence or a docs site. The `--json` flag is the integration point for test harnesses that want to inspect the bundle programmatically.

src/render/

### Renderers

`json.ts`, `text.ts`, `ansi.ts`, `png.ts`, `svg.ts`, `video.ts`. The renderer set handles both colour and monochrome terminals, with optional cursor visibility and a configurable final-frame hold.

src/recording.ts

### Recording format

`RECORDING_VERSION` tracks the versioned `.termctrl` container. `duration`, `frameAt`, `finalFrame`, and `frameAtMarker` read it back.

src/evidence.ts

### Evidence bundle

Same shape as the sibling engines: `createEvidenceBundle` writes `screenshot.png`, `demo.mp4`, `preview.gif`, `manifest.json`, and `pr.md` into `--out DIR`.

## Source anchors

| Concern | File |
| --- | --- |
| CLI | `packages/terminal-control/src/cli.ts` |
| Daemon / session | `packages/terminal-control/src/daemon.ts` + `daemon-client.ts`, `session.ts`, `manager.ts` |
| Recording format | `packages/terminal-control/src/recording.ts` |
| Evidence bundle | `packages/terminal-control/src/evidence.ts` |
| Renderers | `packages/terminal-control/src/render/ansi.ts`, `json.ts`, `png.ts`, `svg.ts`, `text.ts`, `video.ts` |
| Key chord helpers | `packages/terminal-control/src/keys.ts` |
| Native driver source | `packages/terminal-control/target/` |
| Tests | `packages/terminal-control/test/` |

---

Source: https://nikcli-ai.dev/docs/terminal-control