aiterm-mcp

Overview Schema Source Related Servers Discussions Admin

pty_send

Send commands or prompts to a PTY or agent session. Supports automatic dispatch to coding agents, image attachments, and completion sentinels for reliable output detection.

Instructions

セッションへテキストを送る。通常PTYへは送信のみ（出力は pty_read で取得）。agent session（launcher起動）への send は自動で 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 を使う。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送信では指定できない
`session_id`	Yes

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.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.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden, and it is exceptionally transparent. It discloses auto-dispatch behavior, immediate return with receipt event_cursor, fire-and-forget semantics, parent-specific answer delivery, exit codes (0/3/4/7), default timeout, non-blocking foreground execution, and when polling is unnecessary.

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 content is valuable but presented as one long, dense paragraph with repeated caveats like 'ポーリング不要' appearing twice. It is front-loaded with the core purpose, but the many parent-specific branches and exit-code details would be far more scannable as structured bullets or sections.

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?

Given the tool's complexity and the absence of annotations, the description is remarkably complete. It covers normal PTY sends, all described parent types, wait_process handling, PowerShell-specific escaping, exit-code semantics, no-polling guarantees, and alternative result-collection tools. The output schema covers return-value details, so no additional return description is needed.

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

Parameters5/5

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

Schema coverage is high at 88%, but the description adds substantial meaning beyond the schema: force is only for non-Claude manual intervention, image is only usable in dispatch, enter always submits in dispatch, mark+enter:false breaks completion detection, and rtk delegates known commands. These are operational constraints not captured in the parameter descriptions.

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

Purpose5/5

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

The description opens with a specific verb and resource, 'セッションへテキストを送る', and immediately distinguishes normal PTY sends from agent-session dispatches. It also differentiates the tool from siblings by naming pty_read, pty_key, claude_turn, and claude_approval as separate paths.

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?

The description gives explicit routing guidance: output is retrieved via pty_read, automatic delivery paths are explained per parent type, durable Claude turns use claude_turn, approval UI uses claude_approval, and force:true is scoped to non-Claude agent sessions. It also explicitly says wait_command must not be used as a process boundary.

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

Deploy Server