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:

1. AI inspects what terminal sessions are open.
2. AI opens a window or tab when needed.
3. AI launches or targets a Codex session.
4. AI sends the task into that session.
5. 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):

brew tap duo121/termhub https://github.com/duo121/termhub
brew install duo121/termhub/termhub

Install from GitHub Releases (without npm):

• termhub__macos-arm64.tar.gz
• termhub__windows-x64.zip

After extraction:

• macOS

chmod +x termhub
./termhub --version

• Windows (PowerShell)

Quick Start For AI

termhub --help
termhub spec
termhub list

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

AI Usage Rules

1. Always resolve (or find) to one exact target before mutating commands.
2. Use --app when multiple backends are active.
3. Use --dry-run before risky operations.
4. Use send --no-enter only when you plan a separate real key submit.
5. 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,down*5,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: