What problem does Aiterm Mcp solve?
Over SSH, one-command-at-a-time leads to re‑authenticating every call, short‑lived sessions piling up, and `fail2ban` locking you out. Aiterm holds one authenticated session, preventing those issues.
Aiterm MCP Server
@kitepon-rgb
Basic information
About Aiterm MCP Server
One persistent tmux-backed terminal for AI agents. ssh, docker exec, and REPLs nest inside a single authenticated session (no re-auth per command). Token-reduced reads, 4-layer completion detection, and a human can co-drive via the shared tmux socket. Install: npx -y aiterm-mcp
Aiterm MCP Server config
Add this server to your MCP-compatible client using the configuration below.
{
"mcpServers": {
"aiterm": {
"command": "npx",
"args": [
"-y",
"aiterm-mcp"
]
}
}
}Aiterm MCP Server tools
14Factory 向け read-only 診断。安全な状態語彙だけを機械可読 JSON で返す（PTY 内容・認証情報・path・環境値は返さない）。
ローカル永続端末(tmux セッション)を1個開き、session_id を返す。tmux サーバ常駐ゆえ本サーバや クライアントが再起動してもセッションは生存する。リモート操作は専用ツールにせず、開いた端末の中で pty_send(session_id, "ssh host") と打って入る。
セッションへテキストを送る。通常PTYへは送信のみ（出力は pty_read で取得）。agent session（launcher起動）への send は自動で dispatch になる: TUI の ready gate と submit 分離を通して即返り、receipt の event_cursor を返す。dispatch した子は投げっぱなしでよい＝親はここで待たない。完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` を親のターンを塞がない別プロセスとして起動して受け、exit を完了通知として扱う（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed。receiptのoutcomeが正で、done以外は未完了。ポーリング不要）。この待ちコマンドを foreground で実行して親のターンを塞ぐことはしない（receipt が実際の起動形を示す）。結果回収は pty_read(agent_transcript:true)、Claude の durable turn は claude_turn を使う。force:true は非Claude agent sessionへの手動介入用の素送信。aiterm相関付きClaudeの承認UIはclaude_approvalを使う。
セッションの出力をトークン削減して読む（既定は前回読取位置からの増分）。削減: 制御文字除去 / 反復圧縮 / head+tail 折りたたみ＋復元ヒント＋メタ併記。agent_transcript:true は agent session の直近完了ターンの最終 assistant メッセージを公開されたvendor記録から平文で返す。長い回答が screen tail で切れた時の回収用。
制御キーを送る（C-c, C-d, Enter, Tab, Up, Down... の別名に対応）。aiterm相関付きClaude sessionではturn相関を守るためC-cだけを許可し、承認UIはclaude_approvalで操作する。
セッションを閉じ、ログ／読取位置を破棄する。同じsession_idへの再試行は安全で、closed／already_closedのstructured receiptを返す。
握っているセッション一覧（名前 / 現在の前面コマンド / attach 状態 / サイズ / agent 情報）。
aiterm相関付きClaude sessionのdurable operationを構造化issue／recoverするmachine-caller専用面。pending／unknown／completedを人間向けerror文字列の解析なしで返し、Observer固有ロジックは持たない。
aiterm相関付きClaudeのactive turn中に表示された権限確認UIを、turn相関を保ったまま検査・応答する専用面。inspectで画面digestと安全な単発Yes/Noだけを取得し、respondは同じoperation・同じdigestが現在も表示中の場合だけ送信する。
起動済みのClaude／Codex／Grok／Composer agent sessionを再起動せず、会話contextを保ったままmodel／reasoning effortを変更する。Claude／Grok／ComposerはCLI標準の/model・/effort、CodexはCLI標準の/model選択画面を使う。
【Claude Code (Anthropic)】の対話エージェントTUIを永続端末に起動する。`claude -p`ではなく、同じ利用者可視sessionへpty_sendで継続入力する。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。通常settingsへlaunch固有Stop hook settingsを加算する。起動前に共有認証を構造化確認し、未認証ならsessionを作らない。aiterm相関付きsession内の/login・/logoutは拒否する。起動して投げたら投げっぱなしでよい＝親はここで待たない。完了通知は起動応答の wait_command（初回prompt時）または pty_send dispatch 後の aiterm-wait --session <id> --cursor <event_cursor> を親のターンを塞がない別プロセスとして起動して受ける（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed。receiptのoutcomeが正で、done以外は未完了。ポーリング不要・foreground実行はしない）。結果回収は pty_read(agent_transcript:true)。Claude の durable turn は claude_turn でも回収できる。
【Codex (OpenAI)】の対話エージェント TUI を永続端末に起動する。実装・レビュー・調査を対話で回す。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。委譲契約を使う完全な呼び出し例: `codex_agent({"prompt":"<依頼>","model":"gpt-5.6-sol","reasoning_effort":"high","cwd":"/absolute/path/to/repo","write_scope":"read-only"})`。turn は pty_send で送る（自動で非ブロック dispatch になる）。起動して投げたら投げっぱなしでよい＝親はここで待たない。完了通知は起動応答の wait_command（初回prompt時）または pty_send dispatch 後の aiterm-wait --session <id> --cursor <event_cursor> を親のターンを塞がない別プロセスとして起動して受ける（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed。receiptのoutcomeが正で、done以外は未完了。ポーリング不要・foreground実行はしない）。結果回収は pty_read(agent_transcript:true)。model / reasoning_effort を引数で指定可（省略時は端末 config／CLI 既定を継承。実効値は起動応答に明示）。
【Grok Build の Grok モデル (既定 grok-4.6)】の対話エージェント TUI を永続端末に起動する。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。turn は pty_send で送る（自動で非ブロック dispatch になる）。起動して投げたら投げっぱなしでよい＝親はここで待たない。完了通知は起動応答の wait_command（初回prompt時）または pty_send dispatch 後の aiterm-wait --session <id> --cursor <event_cursor> を親のターンを塞がない別プロセスとして起動して受ける（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed。receiptのoutcomeが正で、done以外は未完了。ポーリング不要・foreground実行はしない）。結果回収は pty_read(agent_transcript:true)。model／reasoning_effortを引数で指定可。read-only sandboxとagent_configureに対応。
【Grok Build の Composer モデル (既定 grok-composer-2.5-fast)】の対話エージェント TUI を永続端末に起動する。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。turn は pty_send で送る（自動で非ブロック dispatch になる）。起動して投げたら投げっぱなしでよい＝親はここで待たない。完了通知は起動応答の wait_command（初回prompt時）または pty_send dispatch 後の aiterm-wait --session <id> --cursor <event_cursor> を親のターンを塞がない別プロセスとして起動して受ける（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed。receiptのoutcomeが正で、done以外は未完了。ポーリング不要・foreground実行はしない）。結果回収は pty_read(agent_transcript:true)。model／reasoning_effortを引数で指定可。live catalogにComposer modelがなければGrokへfallbackせず明示エラー。read-only sandboxとagent_configureに対応。
Overview
What is Aiterm Mcp?
Aiterm Mcp is a Model Context Protocol server that provides one persistent terminal session (backed by tmux) over stdio. It is designed for AI agents that need to run multiple commands in a single SSH, Docker, or REPL session without reconnecting for each command. The server reduces token usage by truncating output and includes completion detection.
How to use Aiterm Mcp?
Install via claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp (for Claude Code) or run npx -y aiterm-mcp for any MCP client. Requires Node.js 18 or later and tmux. The server exposes six tools: pty_open, pty_send, pty_read, pty_key, pty_close, and pty_list.
Key features of Aiterm Mcp
- One persistent tmux-backed terminal that survives restarts.
- SSH, containers, and REPLs nest via a single
pty_sendcall. - Token-reduced reads with per-command reducers for git, grep, pytest.
- Four-layer completion detection (exit codes,
until, quiescence, timeout). - Human co-driving possible via a shared tmux socket.
- Supports Linux, WSL2, macOS, and native Windows.
Use cases of Aiterm Mcp
- Running multi‑step SSH commands without re‑authenticating each step.
- Executing commands inside Docker containers or REPLs in a single session.
- Automating development workflows (e.g., git, pytest, grep) with reduced token consumption.
- Allowing a human and an AI agent to share the same terminal session.
Frequently asked questions
What are the runtime dependencies?
Node.js 18 or later and `tmux` must be installed on the host.
Which platforms are supported?
Linux, WSL2, macOS, and native Windows.
Can a human interact with the same terminal?
Yes, the terminal is backed by a shared tmux socket, allowing a human to co‑drive the session.
What tools does Aiterm Mcp expose?
Six tools: `pty_open`, `pty_send`, `pty_read`, `pty_key`, `pty_close`, and `pty_list`.
More Developer Tools MCP servers
Mcp-Warden
ermolukLocal-first credential broker for MCP. AI coding agents (Claude Code, Cursor, Codex…) call APIs, SSH and databases through scoped presets; secrets stay in your OS keychain and never enter the agent's context.
4
offprompt
offpromptMCP server that lets Claude Code, Cursor or Codex ask you for API keys on a local page and write them to .env. The agent only ever sees key names.
2
ReactVision MCP
ReactVision, IncMost MCP servers hand your agent documentation. This one hands it a renderer. Write a single React Native codebase that ships native AR to phones and VR to headsets, then let your agent validate every prop, check each pl
Meticulous
Meticulous
Yocoolab
YocoolabMCP server for AI Agents — exposes Yocoolab feedback threads and design selections as tools
1
Comments