splashshell 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoshifumi Tsuda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# splashshell
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/1343f694-1c05-4899-9faa-d2b1138aa3ba" alt="social-image" width="640" />
+</div>
+
+A universal MCP server that exposes any shell (bash, pwsh, powershell, cmd) as a Model Context Protocol server, so AI assistants can run real commands in a real terminal — visible to you, with session state that persists across calls.
+
+- **Real terminal, real output.** Commands run in a visible ConPTY-backed console. You see every character the AI types, just as if you typed it yourself.
+- **Multiple shells side by side.** bash, pwsh, cmd, and others can all be active at the same time. Switch between them per command.
+- **Session state persists.** `cd`, environment variables, and shell history carry across calls — it's one continuous shell, not isolated subprocess spawns.
+- **Shell integration built in.** OSC 633 markers delimit command boundaries cleanly, so output parsing is reliable even for interleaved prompts and long-running commands.
+- **Console re-claim.** Consoles outlive their parent MCP process. When the AI client restarts, the next session reattaches to existing consoles.
+- **Auto cwd handoff.** When a same-shell console is busy, a new one is auto-started in the source console's directory and your command runs immediately — no manual `cd` needed.
+- **Sub-agent isolation.** Allocate per-agent consoles with `is_subagent` + `agent_id` so parallel agents don't clobber each other's shells.
+
+## Architecture
+
+```mermaid
+graph TB
+    Client["MCP Client<br/>(Claude Code, etc.)"]
+
+    subgraph Proxy["splashshell proxy (stdio MCP server)"]
+        CM["Console Manager<br/>(cwd tracking, re-claim,<br/>cache drain, switching)"]
+        Tools["start_console<br/>execute_command<br/>wait_for_completion<br/>read_file / write_file / edit_file<br/>search_files / find_files"]
+    end
+
+    subgraph Consoles["Visible Console Windows (each runs splash --console)"]
+        subgraph C1["#9876 Sapphire (bash)"]
+            PTY1["ConPTY + bash<br/>(+ OSC 633)"]
+        end
+        subgraph C2["#5432 Cobalt (pwsh)"]
+            PTY2["ConPTY + pwsh<br/>(+ OSC 633)"]
+        end
+        subgraph C3["#1234 Topaz (cmd)"]
+            PTY3["ConPTY + cmd.exe<br/>(+ OSC 633 via PROMPT)"]
+        end
+    end
+
+    User["User"] -- "keyboard" --> C1
+    User -- "keyboard" --> C2
+    User -- "keyboard" --> C3
+    Client -- "stdio" --> Proxy
+    CM -- "Named Pipe" --> C1
+    CM -- "Named Pipe" --> C2
+    CM -- "Named Pipe" --> C3
+    CM -. "auto-switch<br/>if busy" .-> C1
+    CM -. "shell routing" .-> C2
+```
+
+## Install
+
+Requires [.NET 9 Runtime](https://dotnet.microsoft.com/download/dotnet/9.0).
+
+```bash
+git clone https://github.com/yotsuda/splashshell.git
+cd splashshell
+dotnet publish -c Release -r win-x64 --no-self-contained -o ./dist
+```
+
+The binary is `./dist/splash.exe`.
+
+## MCP Setup
+
+### Claude Code
+
+```bash
+claude mcp add splash -s user -- C:\path\to\splash.exe
+```
+
+### Claude Desktop
+
+Add to `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "splash": {
+      "command": "C:\\path\\to\\splash.exe"
+    }
+  }
+}
+```
+
+## Tools
+
+### Shell tools
+
+| Tool | Description |
+|------|-------------|
+| `start_console` | Open a visible terminal window. Pick a shell (bash, pwsh, powershell, cmd, or a full path). Optional `cwd`, `banner`, and `reason` parameters. Reuses an existing standby of the same shell unless `reason` is provided. |
+| `execute_command` | Run a pipeline. Optionally specify `shell` to target a specific shell type — finds an existing console of that shell, or auto-starts one. Times out cleanly with output cached for `wait_for_completion`. |
+| `wait_for_completion` | Block until busy consoles finish and retrieve cached output (use after a command times out). |
+
+Status lines include the console name, shell family, exit code, duration, and current directory:
+
+```
+✓ #12345 Sapphire (bash) | Status: Completed | Pipeline: ls /tmp | Duration: 0.6s | Location: /tmp
+```
+
+Each MCP tool call also drains:
+
+- **Cached results** from any console whose timed-out command has since finished
+- **Closed console notifications** when a console window has been closed since the last call
+
+### File tools
+
+Claude Code–compatible file primitives, useful when the MCP client doesn't already provide them.
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read a file with line numbers. Supports `offset` / `limit` for paging through large files. Detects binary files. |
+| `write_file` | Create or overwrite a file. Creates parent directories as needed. |
+| `edit_file` | Replace an exact string in a file. Old string must be unique by default; pass `replace_all` to replace every occurrence. |
+| `search_files` | Search file contents with a regular expression. Returns matching lines with file paths and line numbers. Supports `glob` filtering. |
+| `find_files` | Find files by glob pattern (e.g., `**/*.cs`). Returns matching paths. |
+
+## Multi-shell behavior
+
+splashshell tracks the cwd of every console and can switch transparently between same-shell consoles:
+
+| Scenario | Behavior |
+|---|---|
+| First execute on a new shell | Auto-starts a console; warns so you can verify cwd before re-executing |
+| Active console matches requested shell | Runs immediately |
+| Active console busy, same shell requested | Auto-starts a sibling console **at the source console's cwd** and runs immediately |
+| Switch to a same-shell standby | Prepends `cd` preamble so the command runs in the source cwd, then executes |
+| Switch to a different shell | Warns to confirm cwd (cross-shell path translation is not implemented) |
+| User manually `cd`'d in the active console | Warns so the AI can verify the new cwd before running its next command |
+
+Window titles use the format `#PID Name` (e.g., `#12345 Sapphire`) so you can identify each console at a glance. When the parent MCP process exits, titles change to `#PID ____` to indicate the console is up for re-claim.
+
+## Platform support
+
+- **Windows**: ConPTY + Named Pipe (primary target, fully tested)
+- **Linux/macOS**: Unix PTY fallback (experimental)
+
+## How it works
+
+splashshell runs as a stdio MCP server. When the AI calls `start_console`, splashshell spawns itself in `--console` mode as a ConPTY worker, which hosts the actual shell (cmd.exe, pwsh.exe, bash.exe, etc.) inside a real Windows console window. The parent process streams stdin/stdout over a named pipe, injects shell integration scripts (`ShellIntegration/integration.*`) to emit OSC 633 markers, and parses those markers to delimit command output, track cwd, and capture exit codes.
+
+Result: the AI gets structured command-by-command output, the user gets a real terminal they can type into, and session state (cwd, env, history) persists across every call.
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const exe = join(__dirname, "..", "dist", "splash.exe");
+
+const child = spawn(exe, process.argv.slice(2), {
+  stdio: "inherit",
+  windowsHide: true,
+});
+
+child.on("exit", (code) => process.exit(code ?? 1));
+child.on("error", (err) => {
+  if (err.code === "ENOENT") {
+    console.error(
+      "splash binary not found. This package requires Windows and .NET 9 Desktop Runtime.\n" +
+        "Download: https://dotnet.microsoft.com/download/dotnet/9.0"
+    );
+  } else {
+    console.error(err.message);
+  }
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "splashshell",
+  "version": "0.1.0",
+  "description": "Shared console MCP server for any shell (bash, pwsh, cmd) — AI and user work in the same terminal. Real-time command visibility, interactive prompt support, session persistence, multi-shell management with automatic cwd handoff.",
+  "license": "MIT",
+  "author": "Yoshifumi Tsuda",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yotsuda/splashshell.git"
+  },
+  "homepage": "https://github.com/yotsuda/splashshell",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "shell",
+    "bash",
+    "pwsh",
+    "powershell",
+    "cmd",
+    "terminal",
+    "conpty",
+    "shared-console",
+    "claude",
+    "ai"
+  ],
+  "os": [
+    "win32"
+  ],
+  "bin": {
+    "splash": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ]
+}