Documentation

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 (headless Chromium) and @nikcli-ai/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 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

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

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 and 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/`