aiterm-mcp 0.3.0 → 0.4.0

package/README.ja.md

@@ -8,6 +8,8 @@
 [![npm](https://img.shields.io/npm/v/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
 [![node](https://img.shields.io/node/v/aiterm-mcp)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
+[![install size](https://packagephobia.com/badge?p=aiterm-mcp)](https://packagephobia.com/result?p=aiterm-mcp)
 
 > *(English: [README.md](README.md))*
 
@@ -15,6 +17,31 @@
 
 `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` の 6 ツールだけ。バックエンドは tmux なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
+## クイックスタート（約60秒）
+
+Claude Code なら 1 コマンドで登録 — clone もビルドも不要、`npx` が毎回取得して起動する:
+
+```bash
+claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+```
+
+Claude Code を再起動して、接続を確認:
+
+```bash
+/mcp        # aiterm が connected・6 ツール公開、と出る
+```
+
+最初のセッション — 4 回の呼び出しで、1 個の永続端末:
+
+```text
+pty_open()                          → { session_id: "t1", attach: "tmux -S … attach -t t1" }
+pty_send("t1", "echo hello")        → PTY にコマンドを送る
+pty_read("t1", { wait: true })      → "hello"   （トークン削減・完了検出つき）
+pty_close("t1")                     → 端末を解放
+```
+
+これだけ。`t1` の端末は本物で永続 — `ssh`・`docker exec`・REPL は、そこへ `pty_send` で打ち込む“ただのテキスト”（[なぜ](#なぜ)）。インストールも不要にしたいなら、どの MCP クライアントからでも stdio で `npx -y aiterm-mcp` を起動するだけ。
+
 ## インストール
 
 npm に公開済み。clone もビルドも不要:
@@ -41,6 +68,43 @@ pty_send(id, "uname -a")           → リモートで実行
 pty_read(id, { wait: true })       → 削減済みの出力を読む
 ```
 
+## デモ
+
+<!-- demo gif: drop docs/demo.gif here (asciinema cast or animated GIF of the flow below) -->
+
+決め手の流れ: PTY を 1 個開き、その**中で** SSH にネストし、リモートでコマンドを実行し、**すでにトークン削減された**出力を読む — コマンドごとの接続し直しは無い。
+
+```text
+# 1 — ローカル端末を 1 個握る（tmux 上・再起動を跨ぐ）
+→ pty_open()
+← { session_id: "t1", attach: "tmux -S /…/claude.sock attach -t t1" }
+
+# 2 — その同じ端末の中で SSH にネスト（別ツールではない）
+→ pty_send("t1", "ssh 192.168.1.2")
+← sent
+→ pty_read("t1", { until: "\\$ $" })          # リモートのプロンプト = 「シェルに戻った」
+← user@remote:~$
+
+# 3 — 同じ PTY のまま、リモートでコマンド実行（接続し直し無し）
+→ pty_send("t1", "uname -a")
+→ pty_read("t1", { until: "\\$ $" })
+← Linux remote 6.1.0 #1 SMP x86_64 GNU/Linux
+
+# 4 — ノイズの多いコマンドを、コマンド別 reducer で読む
+→ pty_send("t1", "git status")
+→ pty_read("t1", { until: "\\$ $", rtk: true }) # 自前実装・rtk バイナリ不要
+← ## main…origin/main [ahead 1]
+   M src/core.ts
+   ?? notes.txt
+   [reduced: 制御文字除去 · 重複圧縮 · git-status reducer]
+```
+
+この流れが「デモのための嘘」にならない理由:
+
+- ステップ 2/3 が **`until`**（リモートのプロンプト）を使うのは、**ネスト中は quiescence が原理的に効かない**ため（[完了検出](#完了検出4-層) / [既知の制約](#既知の制約バグではなく仕様)）。ローカルシェルなら `{ wait: true }` だけで足りるが、ネスト中は `until`（または `mark: true`）が要る。
+- 角括弧の `[reduced: …]` 行は `pty_read` が付けるメタ/復元ヒントの例示で、実際の文言は出力に応じて変わる。reducer は **自前実装**の `pty_read({ rtk: true })` 経路で、外部 `rtk` バイナリは不要。
+- `t1` のソケットに人が `attach` すれば、同じ SSH セッションをライブで覗ける（[人が覗く](#人が覗く)）。
+
 ## 仕組み
 
 ```mermaid
@@ -115,7 +179,7 @@ claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp
 
 ## 既知の制約（バグではなく仕様）
 
-- **ネスト中（ssh / docker / REPL）は quiescence が原理的に効かない。** 前面コマンドがシェル集合（bash/sh/zsh/fish/dash）の外になるため。完了検出は `until`（プロンプト等の正規表現）か `mark: true`（終了コード付き sentinel）を使う。
+- **ネスト中（ssh / docker / REPL）は quiescence が原理的に効かない。** 前面コマンドがシェル集合（bash/sh/zsh/fish/dash）の外になるため。ネスト中で `until` 未指定のときは、待っても完了を確定できる信号が無いので、`pty_read({ wait: true })` はフル `timeout` を空費せず出力静止時点で `is_complete=False via nested` と早期に返し、`until`（プロンプト等の正規表現）か `mark: true`（終了コード付き sentinel）の指定を促す。
 - **`is_complete=False` は失敗ではない。** 「timeout 内に完了を観測できなかった」という意味。長時間コマンドでは `timeout` を伸ばすか `until`/`mark` を使う。
 - **破壊ゲートはサンドボックスではなく tripwire。** よくある破壊形だけを弾く。相対パスの `rm`、`$VAR` 展開後に危険化するもの、ssh 先で実行されるコマンドは捕捉しない。
 - **`pty_send({ rtk: true })` は単行コマンドのみ＋外部 `rtk` バイナリが必要**（無ければ素通し）。一方 `pty_read({ rtk: true })` の reducer は自前実装で rtk 非依存。
@@ -138,6 +202,19 @@ npm link           # ローカルで `aiterm-mcp` を PATH に
 
 ロジックは `src/core.ts`（tmux 制御・削減・完了検出・安全）と `src/rtk.ts`（コマンド別 reducer）、公開は `src/index.ts`。設計の出発点と reducer の移植元（pytest reducer は本家 rtk 0.42.0 と出力が byte 一致するよう移植・回帰テストで固定）は `prototype/python/` を参照。
 
+## 試す
+
+1 コマンド、clone もビルドも不要:
+
+```bash
+claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+```
+
+aiterm がトークンの往復を 1 回でも省けたなら、**[リポジトリに star](https://github.com/kitepon-rgb/aiterm-mcp)** を — 他の人に見つけてもらう一番安い方法です。
+
+- **npm:** https://www.npmjs.com/package/aiterm-mcp
+- **Issue / バグ報告:** https://github.com/kitepon-rgb/aiterm-mcp/issues
+
 ## ライセンス
 
 MIT

package/README.md

@@ -8,6 +8,8 @@
 [![npm](https://img.shields.io/npm/v/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
 [![node](https://img.shields.io/node/v/aiterm-mcp)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
+[![install size](https://packagephobia.com/badge?p=aiterm-mcp)](https://packagephobia.com/result?p=aiterm-mcp)
 
 > *(日本語: [README.ja.md](README.ja.md))*
 
@@ -15,6 +17,31 @@
 
 Just six tools — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
 
+## Quickstart (≈60 seconds)
+
+One command registers it in Claude Code — no clone, no build, `npx` fetches it each run:
+
+```bash
+claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+```
+
+Restart Claude Code, then verify the connection:
+
+```bash
+/mcp        # aiterm should show as connected, exposing 6 tools
+```
+
+Your first session — four calls, one persistent terminal:
+
+```text
+pty_open()                          → { session_id: "t1", attach: "tmux -S … attach -t t1" }
+pty_send("t1", "echo hello")        → command sent into the PTY
+pty_read("t1", { wait: true })      → "hello"   (token-reduced, completion detected)
+pty_close("t1")                     → terminal released
+```
+
+That's it. The terminal in `t1` is real and persistent — `ssh`, `docker exec`, a REPL are just text you `pty_send` into it (see [Why](#why)). Prefer no install? Any MCP client can launch `npx -y aiterm-mcp` over stdio directly.
+
 ## Install
 
 It's on npm — no clone, no build:
@@ -41,6 +68,43 @@ pty_send(id, "uname -a")           → run it on the remote
 pty_read(id, { wait: true })       → read the reduced output
 ```
 
+## Demo
+
+<!-- demo gif: drop docs/demo.gif here (asciinema cast or animated GIF of the flow below) -->
+
+The killer flow: open one PTY, nest into SSH *inside it*, run a command on the remote, and read back output that's already been token-reduced — no reconnect per command.
+
+```text
+# 1 — grab one local terminal (lives in tmux; survives restarts)
+→ pty_open()
+← { session_id: "t1", attach: "tmux -S /…/claude.sock attach -t t1" }
+
+# 2 — nest SSH *inside* that same terminal (not a separate tool)
+→ pty_send("t1", "ssh 192.168.1.2")
+← sent
+→ pty_read("t1", { until: "\\$ $" })          # remote prompt = "shell is back"
+← user@remote:~$
+
+# 3 — run a command on the remote, over the SAME PTY (no reconnect)
+→ pty_send("t1", "uname -a")
+→ pty_read("t1", { until: "\\$ $" })
+← Linux remote 6.1.0 #1 SMP x86_64 GNU/Linux
+
+# 4 — a noisy command, read with the per-command reducer
+→ pty_send("t1", "git status")
+→ pty_read("t1", { until: "\\$ $", rtk: true }) # self-contained, no rtk binary needed
+← ## main…origin/main [ahead 1]
+   M src/core.ts
+   ?? notes.txt
+   [reduced: control chars stripped · repeats collapsed · git-status reducer]
+```
+
+Notes that make this accurate, not a demo lie:
+
+- Step 2/3 use **`until`** with the remote prompt because **while nested, quiescence cannot fire by design** — see [Completion detection](#completion-detection-4-layers) and [Known constraints](#known-constraints-by-design-not-bugs). `{ wait: true }` alone works at the local shell; nested needs `until` (or `mark: true`).
+- The bracketed `[reduced: …]` line is illustrative of the meta/restore hint `pty_read` appends; the exact text comes from your output. The reducer is the **self-contained** `pty_read({ rtk: true })` path — no external `rtk` binary required.
+- A human can `attach` to the `t1` socket and watch the same SSH session live (see [A human can watch](#a-human-can-watch)).
+
 ## How it works
 
 ```mermaid
@@ -115,7 +179,7 @@ Before sending, `pty_send` blocks destructive commands (`rm -rf /`, `mkfs`, `dd
 
 ## Known constraints (by design, not bugs)
 
-- **While nested (ssh / docker / REPL), quiescence cannot fire by design**, because the foreground command is no longer in the shell set (bash/sh/zsh/fish/dash). Use `until` (a regex for the prompt etc.) or `mark: true` (an exit-code sentinel) for completion.
+- **While nested (ssh / docker / REPL), quiescence cannot fire by design**, because the foreground command is no longer in the shell set (bash/sh/zsh/fish/dash). When nested with no `until`, `pty_read({ wait: true })` returns early as `is_complete=False via nested` (rather than burning the full `timeout`, since no signal can confirm completion there) with a note to pass `until` (a regex for the prompt) or `mark: true` (an exit-code sentinel) for a confirmed completion.
 - **`is_complete=False` is not a failure.** It means "completion was not observed within `timeout`." For long commands, raise `timeout` or use `until`/`mark`.
 - **The destructive gate is a tripwire, not a sandbox.** It blocks common destructive forms only. It does **not** catch relative-path `rm`, things that become dangerous after `$VAR` expansion, or commands run on the far side of an SSH session.
 - **`pty_send({ rtk: true })` is single-line only and needs the external `rtk` binary** (passthrough without it). The `pty_read({ rtk: true })` reducer, by contrast, is self-contained and rtk-independent.
@@ -138,6 +202,19 @@ npm link           # put `aiterm-mcp` on PATH locally
 
 Logic lives in `src/core.ts` (tmux control, reduction, completion detection, safety) and `src/rtk.ts` (per-command reducers); `src/index.ts` is the MCP surface. The design origin and the reducer's porting source (the pytest reducer is ported to be byte-exact with upstream rtk 0.42.0, locked by regression tests) are in `prototype/python/`.
 
+## Try it
+
+One command, no clone, no build:
+
+```bash
+claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+```
+
+If aiterm saved you a round-trip of tokens, **[star the repo](https://github.com/kitepon-rgb/aiterm-mcp)** — it's the cheapest way to help others find it.
+
+- **npm:** https://www.npmjs.com/package/aiterm-mcp
+- **Issues / bug reports:** https://github.com/kitepon-rgb/aiterm-mcp/issues
+
 ## License
 
 MIT

package/dist/core.js

@@ -332,7 +332,7 @@ async function settleWinLog(name) {
         await sleep(POLL * 1000);
     }
 }
-/** 完了境界の4層: dead / until 一致 / (出力静止 ∧ シェルに戻った) / timeout。 */
+/** 完了境界: dead / until 一致 / (出力静止 ∧ シェル復帰)=quiescent / (ネスト中＋until無しで出力静止)=nested(未確定・早期返却) / timeout。 */
 async function waitCompletion(name, untilRe, timeout) {
     // 締切は単調時計で測る。Date.now() は NTP 補正やサスペンドで巻き戻り、長時間待ちで誤判定する（Python は time.monotonic）。
     const deadline = performance.now() + timeout * 1000;
@@ -362,10 +362,22 @@ async function waitCompletion(name, untilRe, timeout) {
         }
         if (size === lastSize) {
             stable++;
-            if (stable >= STABLE_POLLS && SHELLS.has(paneCurrentCommand(name))) {
-                if (isWin)
-                    await settleWinLog(name);
-                return [true, "quiescent"];
+            if (stable >= STABLE_POLLS) {
+                const fg = paneCurrentCommand(name);
+                if (SHELLS.has(fg)) {
+                    if (isWin)
+                        await settleWinLog(name);
+                    return [true, "quiescent"]; // 出力静止 ∧ シェル復帰 ＝ 確証つき完了
+                }
+                // ネスト中（前面が ssh/docker/REPL 等でシェル集合外）は quiescence の「シェル復帰」条件を
+                // 原理的に満たせない。until 未指定ならこれ以上待っても確証は増えない（until/dead/quiescent の
+                // いずれも発火し得ない）ので、出力が静止した時点で「未確定」のまま早期返却し until/mark を促す。
+                // fg==="" は前面コマンド取得失敗＝ネスト断定不可なので早期返却せず従来どおり timeout まで待つ。
+                if (!until && fg !== "") {
+                    if (isWin)
+                        await settleWinLog(name);
+                    return [false, "nested"];
+                }
             }
         }
         else {
@@ -377,6 +389,17 @@ async function waitCompletion(name, untilRe, timeout) {
         await sleep(POLL * 1000);
     }
 }
+// 完了ステータス → is_complete 表記。確証のある層のみ True（until/dead/quiescent）。
+// timeout と nested（ネスト中・出力静止だが確証なし）は False。nested は until/mark を促す注記を添える。
+function completionSuffix(status) {
+    const complete = status === "until" || status === "dead" || status === "quiescent";
+    let s = ` [is_complete=${complete ? "True" : "False"} via ${status}]`;
+    if (status === "nested")
+        s +=
+            " ネスト中（前面が ssh/docker/REPL 等）は出力静止だけでは完了を確定できません。" +
+                "until（リモートのプロンプト等の正規表現）か mark:true で完了を指定してください。";
+    return s;
+}
 function rtkRewrite(text) {
     if (text.trim().includes("\n"))
         return text;
@@ -506,20 +529,16 @@ export async function readOutput(name, o = {}) {
             const [reduced, rname] = rtk.reduce(cmd, framed);
             if (reduced !== null) {
                 const meta = `[aiterm ${name}: rtk:${rname} 適用 / ~${estimateTokens(reduced)} tok (raw ~${estimateTokens(text)} tok)]`;
-                if (status) {
-                    const complete = status !== "timeout";
-                    return reduced + "\n" + meta + ` [is_complete=${complete ? "True" : "False"} via ${status}]`;
-                }
+                if (status)
+                    return reduced + "\n" + meta + completionSuffix(status);
                 return reduced + "\n" + meta;
             }
         }
         // reducer 非該当 → 汎用削減へフォールバック
     }
     const [body, meta] = reduceOutput(text, name, !o.range);
-    if (status) {
-        const complete = status !== "timeout";
-        return body + "\n" + meta + ` [is_complete=${complete ? "True" : "False"} via ${status}]`;
-    }
+    if (status)
+        return body + "\n" + meta + completionSuffix(status);
     return body + "\n" + meta;
 }
 export function listSessions() {

package/dist/index.js

@@ -12,7 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import * as core from "./core.js";
-const server = new McpServer({ name: "aiterm", version: "0.3.0" });
+const server = new McpServer({ name: "aiterm", version: "0.4.0" });
 function ok(s) {
     return { content: [{ type: "text", text: s }] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AI-driven persistent terminal as a local stdio MCP server (tmux-backed). Holds one local PTY; SSH and containers are just commands you send into it. Token-reducing reads.",
   "keywords": [
     "mcp",