aiterm-mcp

Overview Schema Source Related Servers Discussions Admin

pty_send

セッションへテキストを送る。通常PTYへは送信のみ（出力は pty_read で取得）。agent…

Instructions

セッションへテキストを送る。通常PTYへは送信のみ（出力は pty_read で取得）。agent session（launcher起動）への送信はこのtoolだけで行い、子の状態はAitermが送る時点で見て振り分ける。子のturnが実行中なら各harness標準の操作で現在のturnへ差し込み（mode=agent_steer）、完了は差し込み後の作業の終わりに元の依頼への1回だけ届く。新しいevent_cursorと配送は作らない。それ以外は新しいturnとしてdispatchし（mode=agent_dispatch）、TUI の ready gate と submit 分離を通して即返り、receipt の event_cursor を返す。dispatch した子は投げっぱなしでよい＝親はここで待たない。Codex親とClaude Code親にはAitermが回答本文を自動配送する。parent_deliveryがある場合はwait起動も通常の回答回収も不要。親は作業を続けるかターンを終える。Cursor親にはparent_deliveryとwait_processが付く。作業を続ければ次のツール返りに回答が差し込まれ、ターンを終える前にwait_processを背景で起動するとidle中の完了でも起きられる。ポーリングとpty_read(agent_transcript:true)は不要。その他の親では、完了通知をreceiptの wait_process.executable と wait_process.args をそのまま親のターンを塞がない別プロセスAPIへ渡して受け、PowerShell 7のStart-Processだけは windows_start_process_argument_list を単一文字列として渡す。exit を完了通知として扱う（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed / 7=error（harnessの記録でturnがAPIエラー等で打ち切られた。結果は無い）。receiptのoutcomeが正で、done以外は未完了。ポーリング不要）。wait_command は人間向け互換表示でありprocess境界へ使わない。foreground実行で親のターンを塞がない。自動配送以外の結果回収は pty_read(agent_transcript:true)、Claude の durable turn は claude_turn を使う。require_agent:true はagent登録が無いsessionへ打鍵せず、AGENT_SESSION_REQUIREDで未送信を返す。preface はagent sessionへの送信で本文の前に置く1行。Claude Codeの席では貼り付けの印なしで入れ、本文だけを貼る（前置きが貼り付けの包みの外へ出る）。他のharnessでは前置き・空行・本文を1つで貼る。force:true は非Claude agent sessionへの手動介入用の素送信。aiterm相関付きClaudeの承認UIはclaude_approvalを使う。

Input Schema

TableJSON Schema

Name	Required	Description
`raw`	No	送信前サニタイズを無効化
`rtk`	No	既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）
`mark`	No	完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（POSIX shell と PowerShell に対応。SSH先の現在の標準PS promptも自動判定。PowerShell の rc は成功0／失敗1。fish/csh/tcsh は未対応として送信前に拒否）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key("Enter") で実行される）。
`text`	Yes	送る文字列（コマンド／prompt）。UTF-8で最大64KiB
`enter`	No	末尾で Enter を送る（agent dispatch では常に submit）
`force`	No	非Claude agent sessionでは自動dispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない
`image`	No	添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）。agent session への dispatch だけで使え、harness別の添付手順はaitermが吸収する。通常PTY送信やforce送信では指定できない
`remote`	No	別端末のAitermで実行する時のSSH接続情報。hostだけならssh_configの接続名として使う。Aitermは接続情報を保存・管理しない。passphraseは会話記録に残るため、ssh-agentかpassphrase_env（環境変数名）を推奨する。
`preface`	No	agent session への送信（forceなし）で、本文の前に置く1行。送る文は「preface・空行・text」の並びになる。Claude Codeの席ではprefaceを貼り付けの印なしで入れ、textだけを貼る。Codex／Grok／Cursorの席では1つで貼る。1行・200字以内・制御文字なしで、行頭が記号や空白でなく、@ を含まない文。外れた時と通常PTY送信・force送信・remote付きでは、打鍵前に拒否する
`session_id`	Yes
`require_agent`	No	agent登録が無いsessionは打鍵前に拒否する。force:trueとは併用できない

Output Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	Yes
`schema`	Yes
`vendor`	Yes
`harness`	Yes
`launch_id`	Yes
`session_id`	Yes
`event_cursor`	Yes
`wait_process`	Yes
`submit_residue`	Yes
`parent_delivery`	No
`pane_input_recovery`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.60.1Oct 14, 2026

addedInput schema / properties / preface

Added value: +{
+  "description": "agent session への送信（forceなし）で、本文の前に置く1行。送る文は「preface・空行・text」の並びになる。Claude Codeの席ではprefaceを貼り付けの印なしで入れ、textだけを貼る。Codex／Grok／Cursorの席では1つで貼る。1行・200字以内・制御文字なしで、行頭が記号や空白でなく、@ を含まない文。外れた時と通常PTY送信・force送信・remote付きでは、打鍵前に拒否する",
+  "type": "string"
+}

addedInput schema / properties / require_agent

Added value: +{
+  "default": false,
+  "description": "agent登録が無いsessionは打鍵前に拒否する。force:trueとは併用できない",
+  "type": "boolean"
+}

Changed1 schema field changedv0.45.0Sep 30, 2026

changedOutput schema / properties / vendor / anyOf

Previous value: -[
-  {
-    "enum": [
-      "claude",
-      "codex",
-      "grok",
-      "composer",
-      "cursor"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "claude",
+      "codex",
+      "grok",
+      "cursor"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

Changed2 schema fields changedv0.39.1Sep 26, 2026

addedInput schema / properties / remote

Added value: +{
+  "additionalProperties": false,
+  "description": "別端末のAitermで実行する時のSSH接続情報。hostだけならssh_configの接続名として使う。Aitermは接続情報を保存・管理しない。passphraseは会話記録に残るため、ssh-agentかpassphrase_env（環境変数名）を推奨する。",
+  "properties": {
+    "host": {
+      "pattern": "^(?!-)[A-Za-z0-9._%:\\[\\]-]{1,255}$",
+      "type": "string"
+    },
+    "identity_file": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "passphrase": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "passphrase_env": {
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+      "type": "string"
+    },
+    "port": {
+      "maximum": 65535,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "ssh_options": {
+      "items": {
+        "pattern": "^[A-Za-z][A-Za-z0-9]*=[^\\r\\n]*$",
+        "type": "string"
+      },
+      "maxItems": 32,
+      "type": "array"
+    },
+    "user": {
+      "pattern": "^(?!-)[A-Za-z0-9._@\\\\-]{1,128}$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "host"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / mode / enum

Previous value: -[
-  "sent",
-  "agent_dispatch"
-]New value: +[
+  "sent",
+  "agent_dispatch",
+  "agent_steer"
+]

Changed2 schema fields changedv0.35.0Sep 10, 2026

changedInput schema / properties / mark / description

Previous value: -"完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（POSIX shell と PowerShell に対応。PowerShell の rc は成功0／失敗1。fish/csh/tcsh は未対応として送信前に拒否）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key(\"Enter\") で実行される）。"New value: +"完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（POSIX shell と PowerShell に対応。SSH先の現在の標準PS promptも自動判定。PowerShell の rc は成功0／失敗1。fish/csh/tcsh は未対応として送信前に拒否）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key(\"Enter\") で実行される）。"

addedOutput schema / properties / parent_delivery

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "child_outcome": {
+      "anyOf": [
+        {
+          "enum": [
+            "done",
+            "closed",
+            "rate_limited",
+            "error"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "child_turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "delivery_id": {
+      "type": "string"
+    },
+    "error_code": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "queued_submission_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "state": {
+      "enum": [
+        "waiting",
+        "ready",
+        "sending",
+        "submitted",
+        "failed",
+        "unknown"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "delivery_id",
+    "state",
+    "child_outcome",
+    "child_turn_id",
+    "queued_submission_id",
+    "error_code"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedv0.31.2Sep 8, 2026

addedInput schema / properties / image

Added value: +{
+  "description": "添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）。agent session への dispatch だけで使え、harness別の添付手順はaitermが吸収する。通常PTY送信やforce送信では指定できない",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / pane_input_recovery

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedv0.29.21Sep 2, 2026

changedInput schema / properties / force / description

Previous value: -"破壊的コマンドゲートを越える。非Claude agent sessionではdispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない"New value: +"非Claude agent sessionでは自動dispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない"

Changed2 schema fields changedv0.29.8Aug 29, 2026

addedOutput schema / properties / wait_process

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "args": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "executable": {
+          "type": "string"
+        },
+        "windows_start_process_argument_list": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "executable",
+        "args",
+        "windows_start_process_argument_list"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "schema",
-  "mode",
-  "session_id",
-  "event_cursor",
-  "launch_id",
-  "vendor",
-  "harness",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "mode",
+  "session_id",
+  "event_cursor",
+  "wait_process",
+  "launch_id",
+  "vendor",
+  "harness",
+  "submit_residue"
+]

Changed3 schema fields changedv0.28.0Aug 23, 2026

addedOutput schema / properties / harness

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "claude-code",
+        "codex-cli",
+        "grok-cli",
+        "cursor-cli"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / vendor / anyOf

Previous value: -[
-  {
-    "enum": [
-      "claude",
-      "codex",
-      "grok",
-      "composer"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "claude",
+      "codex",
+      "grok",
+      "composer",
+      "cursor"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / required

Previous value: -[
-  "schema",
-  "mode",
-  "session_id",
-  "event_cursor",
-  "launch_id",
-  "vendor",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "mode",
+  "session_id",
+  "event_cursor",
+  "launch_id",
+  "vendor",
+  "harness",
+  "submit_residue"
+]

Changed1 schema field changedv0.27.9Aug 23, 2026

changedInput schema / properties / mark / description

Previous value: -"完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（ネスト中や非シェル前面でも効く確実な完了検出。手で until を組む必要なし）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key(\"Enter\") で実行される）。"New value: +"完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（POSIX shell と PowerShell に対応。PowerShell の rc は成功0／失敗1。fish/csh/tcsh は未対応として送信前に拒否）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key(\"Enter\") で実行される）。"

Addedv0.22.0Aug 4, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and delivers: mode semantics (agent_steer vs agent_dispatch), no event_cursor creation, fire-and-forget dispatch, parent_delivery behavior per harness, and a complete exit-code contract (0=done, 3=timeout, 4=closed, 7=error) with the receipt outcome being authoritative. Validation rejections (AGENT_SESSION_REQUIRED, preface rejection) are also disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The entirety is one dense paragraph with no segmentation, mixing purpose, mode dispatch, exit codes, harness-specific delivery, preface rules, and validation into a single block. While most sentences carry necessary information, the structure is poorly front-loaded after the first sentence and is exceptionally difficult to scan given 11 parameters and multiple modes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a highly complex tool with 11 parameters, nested remote object, and an output schema (so return values need not be described), the description still supplies the completion-detection contract, wait_process delivery mechanics, and harness-specific exceptions. An agent has enough to call it correctly across the normal, agent, and force paths.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 91%, so the schema documents most parameters and the baseline is 3. The description adds non-duplicative meaning for several: force (raw manual send for non-Claude sessions), require_agent (reject before keystroke), and preface behavior that differs between Claude Code and other harnesses. This exceeds the schema-only baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening states a specific verb+resource ("セッションへテキストを送る") and immediately distinguishes the normal-PTY path (send-only, output via pty_read) from the agent-session dispatch path. It separates itself from siblings by naming pty_read, pty_key, claude_turn, and claude_approval. The core purpose is clear, though it is embedded in a much larger behavioral narrative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Routing guidance is explicit and repeated: use pty_read for output, claude_turn for Claude durable turns, claude_approval for approval UIs, and do not poll. It states when agent_steer applies (turn in flight) vs agent_dispatch (otherwise), and when force/require_agent are appropriate. Alternatives and conditions are named rather than inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server