aiterm-mcp

Overview Schema Source Related Servers Discussions Admin

pty_read

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

Instructions

Input Schema

TableJSON Schema

Name	Required	Description
`raw`	No	削減せず生テキスト
`rtk`	No	直前コマンド別の自前 reducer(git/grep/pytest 等)で縮約
`full`	No	増分でなく全文
`wait`	No	完了まで待つ（dead / mark sentinel 自動検出 / until / 出力静止∧シェル復帰 / timeout）
`lines`	No	末尾 N 行のみ
`until`	No	この文字列が出たら完了とみなす（既定はリテラル部分一致。`$ ` や `[..]` もそのまま探せる）
`remote`	No	別端末のAitermで実行する時のSSH接続情報。hostだけならssh_configの接続名として使う。Aitermは接続情報を保存・管理しない。passphraseは会話記録に残るため、ssh-agentかpassphrase_env（環境変数名）を推奨する。
`screen`	No	描画済みスクリーン(TUI 向け)
`timeout`	No	wait の最大待ち秒数
`line_range`	No	全文からの行範囲 "A:B"
`session_id`	Yes
`until_regex`	No	until を正規表現として扱う（既定 false＝リテラル部分一致。メタ文字を使いたい時のみ true）
`operation_id`	No	Claude operationの期待ID。agent_transcript:true時だけ指定し、古い別operationの結果を拒否する
`agent_transcript`	No	agent session の直近完了ターンの最終 assistant メッセージを返す。Claudeはlaunch相関付きStop hook result、他harnessは通常transcript／session historyを使う。長い回答がscreen tailで切れた時の回収用

Output Schema

TableJSON Schema

Name	Required	Description
`mode`	Yes
`text`	Yes
`schema`	Yes
`vendor`	Yes
`harness`	Yes
`turn_id`	Yes
`raw_chars`	Yes
`session_id`	Yes
`answer_empty`	No	agent_transcriptで、完了したturnの回答が空だった時だけtrue（textは空文字列）。回答を読めなかった時は誤りを返す。terminalではnull

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.60.1Oct 14, 2026

addedOutput schema / properties / answer_empty

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "agent_transcriptで、完了したturnの回答が空だった時だけtrue（textは空文字列）。回答を読めなかった時は誤りを返す。terminalではnull"
+}

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"
+  }
+]

Changed1 schema field 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"
+}

Changed1 schema field changedv0.29.21Sep 2, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "harness": {
+      "anyOf": [
+        {
+          "enum": [
+            "claude-code",
+            "codex-cli",
+            "grok-cli",
+            "cursor-cli"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "mode": {
+      "enum": [
+        "terminal",
+        "agent_transcript"
+      ],
+      "type": "string"
+    },
+    "raw_chars": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "schema": {
+      "const": "aiterm.pty-read-result.v1",
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "text": {
+      "type": "string"
+    },
+    "turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "vendor": {
+      "anyOf": [
+        {
+          "enum": [
+            "claude",
+            "codex",
+            "grok",
+            "composer",
+            "cursor"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "schema",
+    "mode",
+    "session_id",
+    "text",
+    "vendor",
+    "turn_id",
+    "harness",
+    "raw_chars"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.28.0Aug 23, 2026

changedInput schema / properties / agent_transcript / description

Previous value: -"agent session の直近完了ターンの最終 assistant メッセージを返す。Claudeはlaunch相関付きStop hook result、他vendorは通常transcriptを使う。長い回答がscreen tailで切れた時の回収用"New value: +"agent session の直近完了ターンの最終 assistant メッセージを返す。Claudeはlaunch相関付きStop hook result、他harnessは通常transcript／session historyを使う。長い回答がscreen tailで切れた時の回収用"

Addedv0.22.0Aug 4, 2026

TDQS

A3.7/5.0

Behavior4/5

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

With no annotations, the description carries the full load and does well: it discloses that reads are incremental from the last read position by default (an important stateful side effect), what the reduction does (control-char stripping, repetition compression, head+tail folding with restoration hints and metadata), and the non-obvious error semantics for empty turns (empty text plus answer_empty:true instead of a failure). It stops short of stating auth/permission or concurrency behavior.

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

Conciseness4/5

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

Front-loaded with the primary action, then the reduction pipeline, then the agent_transcript special mode, then the edge-case semantics. Compact slash-separated phrasing wastes little, though the reduction-pipeline enumeration is dense and the agent_transcript sentence repeats itself slightly.

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

Completeness4/5

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

For a 14-parameter, output-schema-backed read tool with no annotations, the description covers the two main modes, default scoping behavior, and the empty-turn edge case adequately. It leaves the remote/SSH execution path and wait/timeout interaction entirely to the schema, which is acceptable but a noticeable gap for a tool this broad.

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

Parameters3/5

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

Schema description coverage is 93%, so the schema already documents most of the 14 parameters and the baseline is 3. The description adds cross-parameter meaning for agent_transcript/operation_id and clarifies the incremental default, but says nothing about raw, rtk, full, wait, lines, until, screen, or the remote/SSH object beyond what the schema already states.

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?

States a specific verb+resource (reads session output, token-reduced, incremental by default) and enumerates the reduction pipeline. However, it never differentiates itself from the sibling pty_observe, which sounds like an overlapping read/observation tool, so the agent must guess which one to call.

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

Usage Guidelines3/5

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

One use case is stated explicitly — recovery when a long answer was truncated at the screen tail (agent_transcript mode). Beyond that there is no when-to-use/when-not guidance and no named alternative among the many siblings (pty_observe, claude_turn, etc.). Usage is implied rather than directed.

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

Deploy Server