nova-terminal

CLI-first terminal runtime for agents. It exposes a small set of high-level commands backed by a local daemon, so agents can manage long-running processes, wait for output, inspect state, and clean up sessions via a clean CLI interface.

Install

Global install

npm i -g nova-terminal
pnpm add -g nova-terminal

Zero-install check

npx nova-terminal --help
pnpm dlx nova-terminal --help

Overview

nova-terminal is designed around skill + CLI + local daemon:

• CLI is the primary entrypoint
• Skill teaches agents the recommended workflow
• Local daemon holds long-lived session state over IPC
• Core runtime keeps the existing PTY / output / wait / verify behavior

The default agent workflow is:

run -> wait -> output / verify -> stop

Quick Start

The recommended workflow is:

run -> wait -> output / verify -> stop

First run smoke test

Use a short-lived command to confirm the CLI flow works end to end:

nova-terminal run smoke --cwd . -- pnpm start --help
nova-terminal wait <session-id> --event exit --timeout-ms 30000
nova-terminal output <session-id> --tail 40
nova-terminal stop <session-id>

From source

pnpm install
pnpm dev

Build and run

pnpm build
pnpm start --help

Start only the daemon

pnpm start:daemon
# or
nova-terminal daemon start

Command Model

nova-terminal has two command layers.

High-level commands

Use these first for most agent tasks:

nova-terminal run <name> [--cwd <path>] [--tag <tag>]... -- <command> [args...]
nova-terminal wait <session-id> [--pattern <regex> | --event exit] [--timeout-ms <ms>]
nova-terminal wait-any <id,id,...> --pattern <regex> [--timeout-ms <ms>]
nova-terminal output <session-id> [--tail <n>] [--since <ms>] [--search <regex>] [--stream <stdout|stderr|all>] [--limit <n>] [--clear]
nova-terminal verify <session-id> [--output-contains <regex>] [--output-not-contains <regex>] [--exit-code <n>] [--process-alive] [--process-exited]
nova-terminal stop <session-id>

Advanced commands

Use these for diagnostics, bulk operations, and fallback handling:

nova-terminal input write <session-id> <data>
nova-terminal input key <session-id> <key>
nova-terminal input keys

nova-terminal session list
nova-terminal session get <session-id>
nova-terminal session signal <session-id> <signal>
nova-terminal session delete <session-id>
nova-terminal session list-by-tag <tag>
nova-terminal session tags
nova-terminal session delete-batch <id,id,...>

nova-terminal system ports [--port <port> | --range <start-end>]
nova-terminal system processes [--name <name>] [--limit <n>]
nova-terminal system resources

nova-terminal files list
nova-terminal files tail <path> [--lines <n>]

nova-terminal daemon start
nova-terminal daemon status
nova-terminal daemon stop
nova-terminal daemon gc

CLI help

nova-terminal --help now mirrors this structure directly:

• recommended workflow first
• quick-start commands next
• primary commands before advanced commands
• daemon management and sandbox options after the core path

No subcommand behavior

Running nova-terminal without a subcommand uses the default local daemon transport.

Common Workflows

For fuller agent-oriented walkthroughs, see Agent Examples.

Dev server

nova-terminal run frontend --cwd . -- pnpm dev
nova-terminal wait <session-id> --pattern "ready|listening"
nova-terminal output <session-id> --tail 40

Tagged session groups

nova-terminal run frontend --tag web --tag dev --cwd . -- pnpm dev
nova-terminal run api --tag web --tag api --cwd . -- pnpm start
nova-terminal session list-by-tag web

Tests

nova-terminal run tests --cwd . -- pnpm test
nova-terminal wait <session-id> --event exit --timeout-ms 300000
nova-terminal verify <session-id> --exit-code 0 --output-not-contains "FAIL|ERROR"
nova-terminal stop <session-id>

Troubleshooting

If run fails during PTY startup, diagnose the environment before retrying:

nova-terminal doctor

If you only need a one-shot command while PTY health is degraded, fall back to:

nova-terminal system exec <command> [args...]

Interactive CLI

nova-terminal input write <session-id> "hello\n"
nova-terminal input key <session-id> enter
nova-terminal input keys

input key accepts natural aliases like Enter, Esc, and ArrowUp. If you forget the exact key name, run nova-terminal input keys.

Recommended Agent Usage

Claude Code skill install

curl -o ~/.claude/skills/nova-terminal.md \
  https://raw.githubusercontent.com/chovrio/nova-terminal/main/skills/nova-terminal/SKILL.md

Then in Claude Code, reference the skill directly. Keep agents on the high-level workflow (run -> wait -> output / verify -> stop) whenever possible. For skill discovery and authoring guidance, see skills/README.md.

Agent Examples

These examples show how an agent would use the nova-terminal skill in real work, ordered from simple to complex.

1. Wait for a dev server to become ready

Scenario: The agent starts a frontend or backend server and needs to know when it is ready before continuing.

Agent might say:

I’m using the nova-terminal skill to start the server and wait for a ready signal.

CLI flow:

nova-terminal run frontend --cwd . -- pnpm dev
nova-terminal wait <session-id> --pattern "ready|listening|localhost"
nova-terminal output <session-id> --tail 30

Why this is useful: The agent does not need to poll blindly or rerun the command every turn.

2. Run a long test job and assert success

Scenario: The agent needs to run tests that may take a while and confirm they passed before moving on.

Agent might say:

I’m using the nova-terminal skill to run the test job, wait for exit, and verify the result.

CLI flow:

nova-terminal run tests --cwd . -- pnpm test
nova-terminal wait <session-id> --event exit --timeout-ms 300000
nova-terminal verify <session-id> --exit-code 0 --output-not-contains "FAIL|ERROR"
nova-terminal stop <session-id>

Why this is useful: The agent gets a durable test session plus structured verification instead of inspecting raw output manually.

3. Read incremental output while debugging a stuck process

Scenario: The agent already started a process earlier and now wants to inspect only the newest output.

Agent might say:

I’m using the nova-terminal skill to inspect the latest output before deciding whether to retry or stop the process.

CLI flow:

nova-terminal output <session-id> --tail 50 --stream stderr
nova-terminal output <session-id> --search "error|Error|ERROR" --tail 50
nova-terminal session get <session-id>

Why this is useful: The agent can debug the live process without restarting it or flooding the context with unfiltered logs.

4. Drive an interactive CLI or prompt

Scenario: The agent needs to respond to a prompt, send input, or interrupt a running command.

Agent might say:

I’m using the nova-terminal skill because this command needs interactive terminal input.

CLI flow:

nova-terminal input write <session-id> "yes\n"
nova-terminal input key <session-id> enter
nova-terminal input key <session-id> ctrl_c

Why this is useful: The agent can continue an interactive workflow instead of abandoning it and rerunning from scratch.

5. Run a full multi-step agent workflow

Scenario: The agent needs to start a service, wait for readiness, inspect output, run checks, and clean up when done.

Agent might say:

I’m using the nova-terminal skill for the full run -> wait -> output / verify -> stop workflow so the process stays available across steps.

CLI flow:

nova-terminal run app --cwd . -- pnpm dev
nova-terminal wait <session-id> --pattern "ready|listening" --timeout-ms 30000
nova-terminal output <session-id> --tail 40
nova-terminal verify <session-id> --process-alive
nova-terminal stop <session-id>

Why this is useful: This is the main agent workflow for long-running processes, interactive tasks, and cross-turn stateful debugging.

Architecture

Agent / User
    -> CLI
    -> IPC transport
    -> Local daemon
    -> application services
    -> core + process runtime

Main modules

• src/cli.ts — top-level CLI parser and dispatcher
• src/cli/* — command wrappers and daemon client
• src/daemon/* — daemon bootstrap, transport, recovery, state dir
• src/application/* — transport-agnostic service orchestration
• src/core/* — session, output, wait, verify, inspection logic
• src/process/* — PTY and exec process management

Development

pnpm typecheck
pnpm test
pnpm test:unit
pnpm test:integration
pnpm build

Notes

• The project uses CLI as the primary interface (no MCP server).
• The daemon is an implementation detail behind the CLI, not the product surface.

License

MIT