duo121/termhub: TermHub: Open-source native terminal control gateway for AI Agents. Let LLMs/AI Agents fully control & automate iTerm2 / Windows Terminal: manage tabs, panes, sessions, send commands, capture output programmatically. · GitHub

中文说明

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)

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:

chmod +x termhub
./termhub --version

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.

termhub now ships an SDK preview entry:

import 💬 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);

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 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:

termhub press --session <id|handle> --key enter
termhub press --session <id|handle> --combo ctrl+c
termhub press --session <id|handle> --sequence "esc,down*3,enter" --delay 60

Open a new iTerm2 window:

termhub open --app iterm2 --window

List all iTerm2 tabs:

termhub list --app iterm2

Close a specific tab by title:

termhub resolve --title Task1
termhub find --title Task1
termhub close --session <resolved-handle-or-session-id>

Read current Terminal tab (last 50 lines):

termhub resolve --app terminal --current-window --current-tab --current-session
termhub capture --app terminal --session terminal:session:<window-id>:<tab-index> --lines 50

Run command in Windows Terminal tab titled API:

termhub resolve --app windows-terminal --title API
termhub send --app windows-terminal --session windows-terminal:session:<window-handle>:<tab-index> --text "npm test"

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 <id|handle> --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.

• --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.