aiterm-mcp 0.20.0 → 0.20.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ja.md +76 -13
- package/README.md +75 -14
- package/package.json +13 -5
package/README.ja.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
> **Claude Code から Codex CLI の対話 TUI を操作する——スラッシュコマンドや [`$imagegen`](https://learn.chatgpt.com/docs/image-generation#generate-or-edit-an-image) のようなスキルまで、MCP越しに使える。**
|
|
2
|
+
|
|
1
3
|
<p align="center">
|
|
2
4
|
<img src=".github/og.svg" alt="aiterm-mcp — AI が握る 1 本の永続 MCP 端末。その中へ他のコーディングエージェント（Claude/Codex/Grok/Composer）を起動する（tmux ベースの stdio MCP サーバ）" width="100%">
|
|
3
5
|
</p>
|
|
@@ -6,6 +8,7 @@
|
|
|
6
8
|
|
|
7
9
|
[](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml)
|
|
8
10
|
[](https://www.npmjs.com/package/aiterm-mcp)
|
|
11
|
+
[](https://www.npmjs.com/package/aiterm-mcp)
|
|
9
12
|
[](https://nodejs.org)
|
|
10
13
|
[](LICENSE)
|
|
11
14
|
[](https://packagephobia.com/result?p=aiterm-mcp)
|
|
@@ -20,6 +23,70 @@
|
|
|
20
23
|
>
|
|
21
24
|
> *MCP = Model Context Protocol — Claude Code のようなツールが AI に機能を差し込むためのオープン標準。*
|
|
22
25
|
|
|
26
|
+
kitepon.devを運営する[クオ（@QLyun35332）](https://x.com/QLyun35332)が
|
|
27
|
+
開発・メンテナンスしています。
|
|
28
|
+
|
|
29
|
+
## MCPクライアントへ導入
|
|
30
|
+
|
|
31
|
+
cloneもビルドも不要。どのクライアントでも公開パッケージを次のコマンドで起動する:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx -y aiterm-mcp
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**Node.js ≥ 18** と **tmux** が必要。Codexを操作する場合は、Codex CLIの導入と認証も必要。
|
|
38
|
+
|
|
39
|
+
### Claude Code
|
|
40
|
+
|
|
41
|
+
ユーザー設定へ追加する:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
プロジェクト設定として共有する場合は、`.mcp.json` に次を置く:
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"mcpServers": {
|
|
52
|
+
"aiterm": {
|
|
53
|
+
"command": "npx",
|
|
54
|
+
"args": ["-y", "aiterm-mcp"]
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Claude Desktop
|
|
61
|
+
|
|
62
|
+
`claude_desktop_config.json` に次のサーバーを追加する:
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"mcpServers": {
|
|
67
|
+
"aiterm": {
|
|
68
|
+
"command": "npx",
|
|
69
|
+
"args": ["-y", "aiterm-mcp"]
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Cursor
|
|
76
|
+
|
|
77
|
+
プロジェクトでは `.cursor/mcp.json`、全体設定では `~/.cursor/mcp.json` に保存する:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"mcpServers": {
|
|
82
|
+
"aiterm": {
|
|
83
|
+
"command": "npx",
|
|
84
|
+
"args": ["-y", "aiterm-mcp"]
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
23
90
|
**工場での役割:** aiterm-mcpはdotagents開発工場が管理する自作コア10製品の一つです。
|
|
24
91
|
永続PTYと外部agent実行レーンを所有し、dotagentsが製品横断の導入・統合契約を所有します。
|
|
25
92
|
|
|
@@ -27,12 +94,14 @@
|
|
|
27
94
|
|
|
28
95
|
13 ツール: 6 つの **PTY ツール**（`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`）で 1 本の永続端末を開き・操作し・読む。加えて 4 つの **エージェント起動ツール**（`claude_agent` / `codex_agent` / `grok_agent` / `composer_agent`）が別のコーディングエージェントの TUI を新しい端末の中に起動し、`claude_turn`がdurable caller向けの構造化issue／recoveryを、`claude_approval`がmanaged Claudeの相関済み承認UI中継を、`diagnostics`が安全なfactory readinessを返す。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
|
|
29
96
|
|
|
30
|
-
**v0.
|
|
31
|
-
|
|
32
|
-
`
|
|
33
|
-
|
|
97
|
+
**v0.20.0 を 2026-07-26 に公開。** 待たずに一度だけ観測する
|
|
98
|
+
`aiterm-wait --timeout 0` の未完了を、実際に待って終わらなかった`timeout`と区別し、
|
|
99
|
+
`running`（exit 5）で返すようにしました。v0.19系では相関済みmanaged Claude approval中継を追加し、
|
|
100
|
+
複数行shell配送を維持し、native Windowsのfactory diagnosticsを拡張しました。
|
|
101
|
+
v0.16/0.17以来、親エージェントはaiterm上で一切ブロックしません:
|
|
34
102
|
agent session への send は常に非ブロック dispatch になり、完了待ちは `aiterm-wait` 一本
|
|
35
|
-
（exit code が receipt の outcome を映す: 0=done / 3=timeout=未完了 /
|
|
103
|
+
（exit code が receipt の outcome を映す: 0=done / 3=timeout=未完了 /
|
|
104
|
+
4=closed / 5=running=待たない観測）、初回 prompt 付き
|
|
36
105
|
launch は structured receipt にコピペ可能な `wait_command` を含む。factory diagnostics と local
|
|
37
106
|
runtime-error store は canonical dotagents config の `collection.enabled: true` が明示された
|
|
38
107
|
場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
|
|
@@ -134,13 +203,7 @@ $ aiterm-wait --session codex1 --cursor <event_cursor> # exit 0=done / 3=timeo
|
|
|
134
203
|
|
|
135
204
|
上の採取で私が触ったのは 2 本の `⋮` 行（長い head/tail を README 用に省略）と長すぎる grep 行 1 本の truncate だけ——`〈…〉` マーカー・トークン数・各 `is_complete` はツールが出した通り。（`until` は末尾スペース無しの `">>>"` を使う——採取されるプロンプトは末尾が削られるので `">>> "` だと外れて `timeout` に落ちる。）ネスト中は `until`（内側プロンプト）か `mark: true` を渡すこと——そこでは quiescence が原理的に効かないため（[完了検出](#完了検出5-層) / [既知の制約](#既知の制約バグではなく仕様)）。同じ tmux ソケットに人が `attach` すれば、これらをライブで覗ける（[人が覗く](#人が覗く)）。
|
|
136
205
|
|
|
137
|
-
##
|
|
138
|
-
|
|
139
|
-
Claude Code なら 1 コマンドで登録——clone もビルドも不要、`npx` が毎回取得して起動する:
|
|
140
|
-
|
|
141
|
-
```bash
|
|
142
|
-
claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
|
|
143
|
-
```
|
|
206
|
+
## 最初の実行（約60秒）
|
|
144
207
|
|
|
145
208
|
Claude Code を再起動して、接続を確認:
|
|
146
209
|
|
|
@@ -170,7 +233,7 @@ npm i -g aiterm-mcp
|
|
|
170
233
|
claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp
|
|
171
234
|
```
|
|
172
235
|
|
|
173
|
-
`~/.claude.json`
|
|
236
|
+
`~/.claude.json` に登録され、初回に承認プロンプトが出る。クライアント別のJSONは[MCPクライアントへ導入](#mcpクライアントへ導入)を参照。
|
|
174
237
|
|
|
175
238
|
## ヘッドレス: 端末に人が居ない
|
|
176
239
|
|
package/README.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
> **Drive Codex CLI's interactive TUI from Claude Code — including slash commands and skills such as [`$imagegen`](https://learn.chatgpt.com/docs/image-generation#generate-or-edit-an-image) — through MCP.**
|
|
2
|
+
|
|
1
3
|
<p align="center">
|
|
2
4
|
<img src=".github/og.svg" alt="aiterm-mcp — one persistent MCP terminal your AI drives, and launches other coding agents (Claude/Codex/Grok/Composer) into (tmux-backed stdio MCP server)" width="100%">
|
|
3
5
|
</p>
|
|
@@ -6,6 +8,7 @@
|
|
|
6
8
|
|
|
7
9
|
[](https://github.com/kitepon-rgb/aiterm-mcp/actions/workflows/ci.yml)
|
|
8
10
|
[](https://www.npmjs.com/package/aiterm-mcp)
|
|
11
|
+
[](https://www.npmjs.com/package/aiterm-mcp)
|
|
9
12
|
[](https://nodejs.org)
|
|
10
13
|
[](LICENSE)
|
|
11
14
|
[](https://packagephobia.com/result?p=aiterm-mcp)
|
|
@@ -20,6 +23,69 @@
|
|
|
20
23
|
>
|
|
21
24
|
> *MCP = Model Context Protocol — the open standard that lets tools like Claude Code plug capabilities into an AI.*
|
|
22
25
|
|
|
26
|
+
Built and maintained by [Quo](https://x.com/QLyun35332) at kitepon.dev.
|
|
27
|
+
|
|
28
|
+
## Install in your MCP client
|
|
29
|
+
|
|
30
|
+
No clone or build is required. Each client launches the published package with:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npx -y aiterm-mcp
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Requires **Node.js ≥ 18** and **tmux**. Driving Codex also requires the Codex CLI to be installed and authenticated.
|
|
37
|
+
|
|
38
|
+
### Claude Code
|
|
39
|
+
|
|
40
|
+
Add it for your user account:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Or commit this as a project-scoped `.mcp.json`:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"mcpServers": {
|
|
51
|
+
"aiterm": {
|
|
52
|
+
"command": "npx",
|
|
53
|
+
"args": ["-y", "aiterm-mcp"]
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Claude Desktop
|
|
60
|
+
|
|
61
|
+
Add this server to `claude_desktop_config.json`:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"mcpServers": {
|
|
66
|
+
"aiterm": {
|
|
67
|
+
"command": "npx",
|
|
68
|
+
"args": ["-y", "aiterm-mcp"]
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Cursor
|
|
75
|
+
|
|
76
|
+
Save this as `.cursor/mcp.json` for the project, or `~/.cursor/mcp.json` globally:
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"mcpServers": {
|
|
81
|
+
"aiterm": {
|
|
82
|
+
"command": "npx",
|
|
83
|
+
"args": ["-y", "aiterm-mcp"]
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
23
89
|
**Factory role:** aiterm-mcp is one of the ten self-owned core products managed by
|
|
24
90
|
the dotagents development factory. It owns the persistent PTY and external-agent
|
|
25
91
|
execution lane; dotagents owns the cross-product installation and integration
|
|
@@ -29,14 +95,15 @@ contract.
|
|
|
29
95
|
|
|
30
96
|
Thirteen tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal, four **agent launchers** — `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` — that each start another coding agent's TUI inside a fresh one, `claude_turn` for durable structured issue/recovery, `claude_approval` for correlated managed-Claude approval prompts, and `diagnostics` for safe factory readiness. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
|
|
31
97
|
|
|
32
|
-
**v0.
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
98
|
+
**v0.20.0 was published on 2026-07-26.** It distinguishes a non-blocking
|
|
99
|
+
`aiterm-wait --timeout 0` observation (`running`, exit 5) from a real timed-out
|
|
100
|
+
wait. The v0.19 line added the correlated managed-Claude approval relay,
|
|
101
|
+
preserved multiline shell delivery, and extended factory diagnostics on native
|
|
102
|
+
Windows. As of v0.16/0.17 a parent agent never blocks on aiterm:
|
|
37
103
|
every send to an agent session is a non-blocking dispatch, completion is one
|
|
38
104
|
universal `aiterm-wait` waiter whose exit codes mirror the receipt outcome
|
|
39
|
-
(`0`=done / `3`=timeout, not finished / `4`=closed
|
|
105
|
+
(`0`=done / `3`=timeout, not finished / `4`=closed / `5`=running for a
|
|
106
|
+
zero-time observation), and a launch with an
|
|
40
107
|
initial prompt returns a ready-made `wait_command` in its structured receipt.
|
|
41
108
|
Factory diagnostics and the local runtime-error store collect only when
|
|
42
109
|
canonical dotagents config explicitly sets `collection.enabled: true`;
|
|
@@ -151,13 +218,7 @@ Nesting is just text you send in — here a Python REPL *inside* the same PTY (a
|
|
|
151
218
|
|
|
152
219
|
The only edits to the captures above are the two `⋮` lines (a long head/tail run abbreviated for the README) and one over-long grep line truncated to fit — the `⟨…⟩` marker, the token counts, and every `is_complete` verdict are exactly what the tool printed. (Use `until: ">>>"` without a trailing space — the captured prompt is trimmed, so `">>> "` would miss and fall through to `timeout`.) While nested, pass `until` (the inner prompt) or `mark: true`, because quiescence cannot fire there by design — see [Completion detection](#completion-detection-5-layers) and [Known constraints](#known-constraints-by-design-not-bugs). A human can `attach` to the same tmux socket and watch any of this live (see [A human can watch](#a-human-can-watch)).
|
|
153
220
|
|
|
154
|
-
##
|
|
155
|
-
|
|
156
|
-
One command registers it in Claude Code — no clone, no build, `npx` fetches it each run:
|
|
157
|
-
|
|
158
|
-
```bash
|
|
159
|
-
claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
|
|
160
|
-
```
|
|
221
|
+
## First run (≈60 seconds)
|
|
161
222
|
|
|
162
223
|
Restart Claude Code, then verify the connection:
|
|
163
224
|
|
|
@@ -187,7 +248,7 @@ npm i -g aiterm-mcp
|
|
|
187
248
|
claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp
|
|
188
249
|
```
|
|
189
250
|
|
|
190
|
-
This registers it in `~/.claude.json`; you'll get an approval prompt the first time.
|
|
251
|
+
This registers it in `~/.claude.json`; you'll get an approval prompt the first time. For client-specific JSON, see [Install in your MCP client](#install-in-your-mcp-client).
|
|
191
252
|
|
|
192
253
|
## Headless: no human at the terminal
|
|
193
254
|
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "aiterm-mcp",
|
|
3
|
-
"version": "0.20.
|
|
3
|
+
"version": "0.20.2",
|
|
4
4
|
"mcpName": "io.github.kitepon-rgb/aiterm-mcp",
|
|
5
|
-
"description": "
|
|
5
|
+
"description": "Persistent tmux terminal MCP that lets Claude Code drive Codex CLI's interactive TUI, including slash commands and $imagegen. Also runs durable PTY sessions for SSH, containers, REPLs, and coding agents.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"mcp",
|
|
8
8
|
"mcp-server",
|
|
@@ -17,11 +17,18 @@
|
|
|
17
17
|
"ai-agent",
|
|
18
18
|
"agent",
|
|
19
19
|
"codex",
|
|
20
|
+
"codex-cli",
|
|
20
21
|
"grok",
|
|
21
|
-
"devtools"
|
|
22
|
+
"devtools",
|
|
23
|
+
"terminal-mcp",
|
|
24
|
+
"persistent-terminal",
|
|
25
|
+
"interactive-cli"
|
|
22
26
|
],
|
|
23
27
|
"license": "MIT",
|
|
24
|
-
"author":
|
|
28
|
+
"author": {
|
|
29
|
+
"name": "Quo / クオ at kitepon.dev",
|
|
30
|
+
"url": "https://x.com/QLyun35332"
|
|
31
|
+
},
|
|
25
32
|
"repository": {
|
|
26
33
|
"type": "git",
|
|
27
34
|
"url": "git+https://github.com/kitepon-rgb/aiterm-mcp.git"
|
|
@@ -37,7 +44,7 @@
|
|
|
37
44
|
"aiterm-wait": "dist/aiterm-wait-cli.js"
|
|
38
45
|
},
|
|
39
46
|
"files": [
|
|
40
|
-
"dist",
|
|
47
|
+
"dist/*.js",
|
|
41
48
|
"README.md",
|
|
42
49
|
"LICENSE"
|
|
43
50
|
],
|
|
@@ -46,6 +53,7 @@
|
|
|
46
53
|
},
|
|
47
54
|
"scripts": {
|
|
48
55
|
"build": "tsc",
|
|
56
|
+
"mcpb:build": "npm run build && node scripts/build-mcpb.mjs && npm ci --omit=dev --ignore-scripts --no-audit --no-fund --prefix dist/mcpb-stage/server && npx --yes @anthropic-ai/mcpb@2.1.2 validate dist/mcpb-stage/manifest.json && npx --yes @anthropic-ai/mcpb@2.1.2 pack dist/mcpb-stage dist/aiterm-mcp.mcpb",
|
|
49
57
|
"prepublishOnly": "npm run build",
|
|
50
58
|
"start": "node dist/index.js",
|
|
51
59
|
"test": "npm run build && node --test test/*.test.mjs"
|