aiterm-mcp

Overview Schema Source Related Servers Discussions Admin

agent_launch

Instructions

エージェントを単一の標準入口から永続sessionへ起動する。harnessはagent loop・認証・hook・transcriptを所有する実行基盤、modelはそのharnessが選ぶ推論モデルであり別軸。Cursor harnessからGPT／Claude／Grok等を選んでも完了相関はCursor方式のまま。ComposerはCursorのmodelの一つで、harnessでもGrokのmodelでもない。harness=cursor-cli と model=composer-2.5-fast（またはcomposer-2.5）で指定する。remoteを付けると、SSHで入った別端末のAitermで同じ起動を行い、完了は同じ形で親へ届く。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。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)。

Input Schema

TableJSON Schema

Name	Required	Description
`cwd`	No	作業ディレクトリ（絶対パス・任意）
`fast`	No	ファスト（harnessの高速の応答。費用や利用量が増える）。省略とfalseは通常の速度で起こす（利用者の設定にfastが残っていても通常）。trueは通常で起こしてから、その席をfastへ切り替える。modelがfastに対応していない時（FAST_MODE_NOT_SUPPORTED）と、modelへfast版のIDを書いてfalseを渡した時（FAST_MODE_MODEL_CONFLICT）は起動を断る。アカウントの都合で使えない時・確かめられない時は、起動を断らずに通常の速度で起こし、返りの fast を false、fast_error に訳を入れる。modelへfast版のIDを直に書いて省略した時だけ、そのIDのまま起こす（返りの fast は true）。
`image`	No	初手プロンプトへ添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）
`model`	No	harnessが選ぶモデル。provider名ではなくlive catalog上のmodel ID
`prompt`	No	起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る
`remote`	No	別端末のAitermで実行する時のSSH接続情報。hostだけならssh_configの接続名として使う。Aitermは接続情報を保存・管理しない。passphraseは会話記録に残るため、ssh-agentかpassphrase_env（環境変数名）を推奨する。
`harness`	Yes	agent loop・session・hook・transcript・認証を所有する実行基盤
`env_vars`	No	現在のMCP processから継承する環境変数名
`write_scope`	No	能力宣言。read-onlyは対応harnessの標準read-only面で実効禁止する
`session_name`	No	Aiterm session名（省略で自動採番）
`trust_project`	No	対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める
`reasoning_effort`	No	harness adapterが標準CLI表現へ変換する思考レベル。Cursorではmodel同時指定が必要
`launch_operation_id`	No	Claude Codeのpromptなしexact replay相関だけで使用
`throughline_source_session`	No	同一端末のThroughline sessionから読み取り専用contextを初手へ注入する
`throughline_supplement_file`	No	Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path

Output Schema

TableJSON Schema

Name	Required	Description
`fast`	No	起こした後の、席のfastの状態（この項目を返さない版の別端末では無い）
`schema`	Yes
`harness`	Yes
`startup`	Yes
`provider`	Yes	旧互換field。新規連携はharnessを使う
`fast_error`	No	fastを頼まれたが、通常の速度で起こした時の訳
`session_id`	Yes
`remote_host`	No	別端末で起動した時の接続先
`write_scope`	No
`event_cursor`	Yes
`wait_command`	Yes
`wait_process`	Yes
`initial_prompt`	Yes
`remote_version`	No	別端末のAiterm版
`submit_residue`	Yes
`parent_delivery`	No
`managed_completion`	Yes
`write_scope_enforcement`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.60.1Oct 14, 2026

addedInput schema / properties / fast

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "ファスト（harnessの高速の応答。費用や利用量が増える）。省略とfalseは通常の速度で起こす（利用者の設定にfastが残っていても通常）。trueは通常で起こしてから、その席をfastへ切り替える。modelがfastに対応していない時（FAST_MODE_NOT_SUPPORTED）と、modelへfast版のIDを書いてfalseを渡した時（FAST_MODE_MODEL_CONFLICT）は起動を断る。アカウントの都合で使えない時・確かめられない時は、起動を断らずに通常の速度で起こし、返りの fast を false、fast_error に訳を入れる。modelへfast版のIDを直に書いて省略した時だけ、そのIDのまま起こす（返りの fast は true）。"
+}

addedOutput schema / properties / fast

Added value: +{
+  "description": "起こした後の、席のfastの状態（この項目を返さない版の別端末では無い）",
+  "type": "boolean"
+}

addedOutput schema / properties / fast_error

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "enum": [
+            "FAST_MODE_NOT_SUPPORTED",
+            "FAST_MODE_UNAVAILABLE",
+            "FAST_MODE_MODEL_CONFLICT",
+            "FAST_MODE_UNCONFIRMED"
+          ],
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "fastを頼まれたが、通常の速度で起こした時の訳"
+}

Changed1 schema field changedv0.45.0Sep 30, 2026

changedOutput schema / properties / provider / enum

Previous value: -[
-  "claude",
-  "codex",
-  "grok",
-  "composer",
-  "cursor"
-]New value: +[
+  "claude",
+  "codex",
+  "grok",
+  "cursor"
+]

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

addedOutput schema / properties / remote_host

Added value: +{
+  "description": "別端末で起動した時の接続先",
+  "type": "string"
+}

addedOutput schema / properties / remote_version

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "別端末のAiterm版"
+}

Changed5 schema fields changedv0.35.0Sep 10, 2026

addedInput schema / properties / trust_project

Added value: +{
+  "description": "対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める",
+  "type": "boolean"
+}

addedOutput schema / properties / initial_prompt

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "not_requested",
+        "not_sent",
+        "submitted_unconfirmed",
+        "started"
+      ],
+      "type": "string"
+    },
+    "turn_started": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "status",
+    "reason",
+    "turn_started"
+  ],
+  "type": "object"
+}

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

addedOutput schema / properties / startup

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "ready",
+        "not_checked",
+        "blocked"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "reason"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "schema",
-  "harness",
-  "provider",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_process",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "initial_prompt",
+  "startup",
+  "harness",
+  "provider",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]

Changed1 schema field changedv0.31.2Sep 8, 2026

addedInput schema / properties / image

Added value: +{
+  "description": "初手プロンプトへ添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedv0.29.21Sep 2, 2026

addedInput schema / properties / throughline_supplement_file

Added value: +{
+  "description": "Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path",
+  "minLength": 1,
+  "type": "string"
+}

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",
-  "harness",
-  "provider",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "harness",
+  "provider",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]

Addedv0.28.0Aug 23, 2026

TDQS

A4.2/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 does so richly: exit-code semantics (0=done, 3=timeout with default 600s, 4=closed, 7=error), receipt.outcome as authoritative, mutation-adjacent behavior (shared HOME/cwd/project-local settings/MCP/plugin/skill/permission-trust), SSH remote execution, injected sub-agent self-recognition/delegation depth/lineage, and per-parent completion-delivery mechanics. This is exactly the behavioral context an agent needs before launching a long-lived process.

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

Conciseness3/5

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

It is appropriately front-loaded with purpose and packed with useful detail, but it reads as one undifferentiated run-on block with no structure, and there is redundancy ("ポーリング不要" and the polling/no-pty_read point are stated twice). A dense topic like this would benefit from segmentation; as written, key exit-code and delivery facts are easy to lose in the wall of text.

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 15-parameter, nested-schema, long-running launch tool with an output schema available, the description supplies the missing operational context: completion correlation, exit-code interpretation, absence of required polling, parent-specific delivery paths, and remote execution behavior. Nothing an agent needs to call and correctly follow up on this tool is absent.

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 100%, so the baseline is 3 and the schema already documents fast, cwd, remote, image, etc. in detail. The description earns above baseline by explaining the harness-vs-model conceptual split and the remote semantics (same launch on another machine's Aiterm, completion returned in the same shape), which are not obvious from the raw property names.

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 sentence states a specific verb+resource — launching an agent into a persistent session from a single standard entry — and the rest carefully disambiguates the two axes (harness = execution substrate owning agent loop/auth/hook/transcript; model = the inference model the harness selects). That is genuinely clarifying. It does not, however, differentiate itself from the per-harness siblings claude_agent/codex_agent/grok_agent, which an agent might reasonably confuse with this tool.

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

Usage Guidelines4/5

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

It gives clear downstream guidance: dispatch is fire-and-forget for the parent, wait/polling is unnecessary, parent_delivery exists for Codex and Claude Code parents, Cursor parents should background wait_process, other parents should forward receipt wait_process args, and result collection outside auto-delivery goes through pty_read(agent_transcript:true). It also warns that wait_command is a human-facing compatibility display, not a process boundary. It stops short of stating when to prefer this tool over the harness-specific siblings.

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

Deploy Server