Aiterm Mcp

by kitepon-rgb

348 downloads

Not rated

GitHub

Developer Tools

About

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

Details

Author: kitepon-rgb
Downloads: 348
Categories: Developer Tools

- One persistent tmux-backed terminal that survives restarts.
- SSH, containers, and REPLs nest via a single pty_send call.
- 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.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Aiterm Mcp

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

From the repository

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.

`diagnostics`

Factory 向け read-only 診断。安全な状態語彙だけを機械可読 JSON で返す（PTY 内容・認証情報・path・環境値は返さない）。

`pty_open`

ローカル永続端末(tmux セッション)を1個開き、session_id を返す。tmux サーバ常駐ゆえ本サーバやクライアントが再起動してもセッションは生存する。リモート操作は専用ツールにせず、開いた端末の中で pty_send(session_id, "ssh host") と打って入る。

`pty_send`

セッションへテキストを送る。通常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を使う。

`pty_read`

セッションの出力をトークン削減して読む（既定は前回読取位置からの増分）。削減: 制御文字除去 / 反復圧縮 / head+tail 折りたたみ＋復元ヒント＋メタ併記。agent_transcript:true は agent session の直近完了ターンの最終 assistant メッセージを公開されたvendor記録から平文で返す。長い回答が screen tail で切れた時の回収用。

`pty_key`

制御キーを送る（C-c, C-d, Enter, Tab, Up, Down... の別名に対応）。aiterm相関付きClaude sessionではturn相関を守るためC-cだけを許可し、承認UIはclaude_approvalで操作する。

`pty_close`

セッションを閉じ、ログ／読取位置を破棄する。同じsession_idへの再試行は安全で、closed／already_closedのstructured receiptを返す。

`pty_list`

握っているセッション一覧（名前 / 現在の前面コマンド / attach 状態 / サイズ / agent 情報）。

`claude_turn`

aiterm相関付きClaude sessionのdurable operationを構造化issue／recoverするmachine-caller専用面。pending／unknown／completedを人間向けerror文字列の解析なしで返し、Observer固有ロジックは持たない。

`claude_approval`

aiterm相関付きClaudeのactive turn中に表示された権限確認UIを、turn相関を保ったまま検査・応答する専用面。inspectで画面digestと安全な単発Yes/Noだけを取得し、respondは同じoperation・同じdigestが現在も表示中の場合だけ送信する。

`agent_configure`

起動済みのClaude／Codex／Grok／Composer agent sessionを再起動せず、会話contextを保ったままmodel／reasoning effortを変更する。Claude／Grok／ComposerはCLI標準の/model・/effort、CodexはCLI標準の/model選択画面を使う。

`claude_agent`

【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_agent`

【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_agent`

【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に対応。

`composer_agent`

【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に対応。

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "aiterm mcp": {
            "aiterm": {
                "command": "npx",
                "args": [
                    "-y",
                    "aiterm-mcp"
                ]
            }
        }
    }
}

McpServers

{
    "aiterm": {
        "command": "npx",
        "args": [
            "-y",
            "aiterm-mcp"
        ]
    }
}

aiterm-mcp

Give an AI one persistent terminal as a stdio MCP server. It holds one local PTY; ssh, docker exec, and REPLs are just text you send into it — so the AI stops reconnecting for every command. Reads come back token-reduced.

Why

Over SSH, one-command-at-a-time means re-authenticating every call, short-lived sessions piling up, and fail2ban locking you out of your own box. aiterm holds one authenticated session, so that never happens.

Install (Claude Code)


claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp


Any MCP client: run

npx -y aiterm-mcp

 over stdio. Needs Node ≥ 18 and tmux.

What you get

- One persistent tmux-backed terminal (survives restarts)
- SSH / containers / REPLs nest with one

pty_send

 — authenticate once, one session
- Token-reduced reads (per-command reducers for git / grep / pytest)
- 4-layer completion detection (exit /

until

 / quiescence / timeout)
- A human can co-drive via the shared tmux socket

Six tools:

pty_open / pty_send / pty_read / pty_key / pty_close / pty_list`. MIT · Linux / WSL2 / macOS / native Windows. Repo: https://github.com/kitepon-rgb/aiterm-mcp

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

diagnostics

pty_open

pty_send

pty_read

pty_key

pty_close

pty_list

claude_turn

claude_approval

agent_configure

claude_agent

codex_agent

grok_agent

composer_agent

Claude Desktop / Cursor

McpServers

aiterm-mcp

Why

Install (Claude Code)

What you get

Install

More like this

Sentry

Github

Git

GitLab

Context 7

Playwright

`diagnostics`

`pty_open`

`pty_send`

`pty_read`

`pty_key`

`pty_close`

`pty_list`

`claude_turn`

`claude_approval`

`agent_configure`

`claude_agent`

`codex_agent`

`grok_agent`

`composer_agent`