Show HN: TermHub – Open-source terminal control gateway built for AI Agents

中文说明

termhub is an AI-native terminal control tool.

It is designed for this closed loop:

• AI inspects what terminal sessions are open.

• AI opens a window or tab when needed.

• AI launches or targets a Codex session.

• AI sends the task into that session.

• AI captures only the new output produced after send and returns it to the user.

• Command: termhub

• Alias: thub

• npm package: @duo121/termhub

• macOS backends: iTerm2, Terminal

• Windows backends: Windows Terminal, Command Prompt (CMD)

Install

npm install -g @duo121/termhub

Or Homebrew (macOS):

Install from GitHub Releases (without npm):

• termhub__macos-arm64.tar.gz

• termhub__windows-x64.zip

After extraction:

• macOS

• Windows (PowerShell)

.\termhub.exe --version

Quick Start For AI

Use spec as machine-readable truth and --help as human-readable truth. Both now include a currentSession hint near the top that you can copy directly into --session for AI handoff.

SDK

termhub now ships an SDK preview entry:

import { createTermhubClient } from "@duo121/termhub/sdk";

Core SDK capabilities:

• Open/close terminal targets.

• Find/resolve terminal sessions.

• Send keyboard text and key events (key / combo / sequence).

• Mouse click simulation on terminal target (mouseClick) on macOS.

Platform notes:

• macOS (iTerm2 / Terminal): keyboard + mouse click are supported.

• Windows (Windows Terminal / CMD): keyboard control is supported; mouseClick currently returns unsupported.

SDK quick example:

import { createTermhubClient } from "@duo121/termhub/sdk";

const client = createTermhubClient({ app: "iterm2" });

const opened = await client.open({ scope: "tab" }); await client.send({ session: opened.target.handle, text: "echo hello from sdk" }); await client.press({ session: opened.target.handle, key: "enter" }); const output = await client.capture({ session: opened.target.handle, lines: 20 });

console.log(output.text);`

Command Map

Top-Level Command What It Does Common Secondary Flags

open Open terminal window or tab --app --window --tab --dry-run

list List running windows/tabs/sessions --app --compact

resolve / find Narrow fuzzy target to one exact session --title --title-contains --session --current-tab

send Send text and optionally await/capture output delta in one step --text --stdin --no-enter --await-output --dry-run

press Send real key/combo/sequence events --key --combo --sequence --repeat --delay

capture Read visible output or delta since latest send checkpoint --session --lines --since-last-send --app

focus Bring target window/session to front --session --app --dry-run

close Close target tab or window --session --app --dry-run

doctor Check platform/backend/automation readiness --app --compact

spec Print machine-readable JSON contract --compact

AI Usage Rules

• Always resolve (or find) to one exact target before mutating commands.

• Use --app when multiple backends are active.

• Use --dry-run before risky operations.

• Use send --no-enter only when you plan a separate real key submit.

• Never fake submit by appending literal newlines inside --text or stdin.

Press Modes

press supports exactly one input mode:

• --key

• --combo (for example ctrl+c, cmd+k)

• --sequence (for example esc,down5,enter)

Extra controls:

• --repeat : only for --key and --combo

• --delay : delay between repeated or sequenced key events

Examples:

Typical AI Scenarios

Open a new iTerm2 window:

termhub open --app iterm2 --window

List all iTerm2 tabs:

termhub list --app iterm2

Close a specific tab by title:

Read current Terminal tab (last 50 lines):

Run command in Windows Terminal tab titled API:

Send-To-Capture Delta Loop

termhub now supports a built-in session checkpoint loop so AI can capture only the new output produced after send.

Basic flow:

termhub send --session --text "npm test" --await-output 1200

How it works:

• send stores a checkpoint for that exact session before writing input.

• send --await-output waits and returns only delta output produced after that send.

• capture --since-last-send remains available when you want a separate explicit read step.

Concurrency:

• Checkpoints are session-scoped, so two AI agents can use different sessions in parallel without conflict.

• State files are stored under ~/.termhub/state by default.

Notes

• --session accepts native session id or namespaced handle.

• Windows focus/send/capture/close rely on PowerShell + UI Automation.

• Windows capture is best-effort based on visible text accessibility.