{"id":48708855,"url":"https://github.com/yotsuda/splashshell","last_synced_at":"2026-04-13T15:00:42.479Z","repository":{"id":350278420,"uuid":"1206131104","full_name":"yotsuda/splashshell","owner":"yotsuda","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.","archived":false,"fork":false,"pushed_at":"2026-04-11T12:58:40.000Z","size":249,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-11T13:27:09.694Z","etag":null,"topics":["ai","bash","claude","cmd","conpty","devops","mcp","mcp-server","model-context-protocol","powershell","pwsh","shared-console","shell","terminal"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/splashshell","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yotsuda.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-09T15:54:36.000Z","updated_at":"2026-04-11T12:58:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"470e810f-27f1-45d7-b3fe-145a57876724","html_url":"https://github.com/yotsuda/splashshell","commit_stats":null,"previous_names":["yotsuda/splashshell"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/yotsuda/splashshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yotsuda%2Fsplashshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yotsuda%2Fsplashshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yotsuda%2Fsplashshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yotsuda%2Fsplashshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yotsuda","download_url":"https://codeload.github.com/yotsuda/splashshell/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yotsuda%2Fsplashshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31757482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T13:27:56.013Z","status":"ssl_error","status_checked_at":"2026-04-13T13:21:23.512Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bash","claude","cmd","conpty","devops","mcp","mcp-server","model-context-protocol","powershell","pwsh","shared-console","shell","terminal"],"created_at":"2026-04-11T13:20:20.728Z","updated_at":"2026-04-13T15:00:42.465Z","avatar_url":"https://github.com/yotsuda.png","language":"C#","readme":"# splashshell\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/1343f694-1c05-4899-9faa-d2b1138aa3ba\" alt=\"social-image\" width=\"640\" /\u003e\n\u003c/div\u003e\n\nA 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.\n\n- **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.\n- **Multiple shells side by side.** bash, pwsh, cmd, and others can all be active at the same time. Switch between them per command.\n- **Session state persists.** `cd`, environment variables, and shell history carry across calls — it's one continuous shell, not isolated subprocess spawns.\n- **Shell integration built in.** OSC 633 markers delimit command boundaries cleanly, so output parsing is reliable even for interleaved prompts and long-running commands.\n- **Console re-claim.** Consoles outlive their parent MCP process. When the AI client restarts, the next session reattaches to existing consoles.\n- **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.\n- **Sub-agent isolation.** Allocate per-agent consoles with `is_subagent` + `agent_id` so parallel agents don't clobber each other's shells.\n\n## Architecture\n\n```mermaid\ngraph TB\n    Client[\"MCP Client\u003cbr/\u003e(Claude Code, etc.)\"]\n\n    subgraph Proxy[\"splashshell proxy (stdio MCP server)\"]\n        CM[\"Console Manager\u003cbr/\u003e(cwd tracking, re-claim,\u003cbr/\u003ecache drain, switching)\"]\n        Tools[\"start_console\u003cbr/\u003eexecute_command\u003cbr/\u003ewait_for_completion\u003cbr/\u003eread_file / write_file / edit_file\u003cbr/\u003esearch_files / find_files\"]\n    end\n\n    subgraph Consoles[\"Visible Console Windows (each runs splash --console)\"]\n        subgraph C1[\"#9876 Sapphire (bash)\"]\n            PTY1[\"ConPTY + bash\u003cbr/\u003e(+ OSC 633)\"]\n        end\n        subgraph C2[\"#5432 Cobalt (pwsh)\"]\n            PTY2[\"ConPTY + pwsh\u003cbr/\u003e(+ OSC 633)\"]\n        end\n        subgraph C3[\"#1234 Topaz (cmd)\"]\n            PTY3[\"ConPTY + cmd.exe\u003cbr/\u003e(+ OSC 633 via PROMPT)\"]\n        end\n    end\n\n    User[\"User\"] -- \"keyboard\" --\u003e C1\n    User -- \"keyboard\" --\u003e C2\n    User -- \"keyboard\" --\u003e C3\n    Client -- \"stdio\" --\u003e Proxy\n    CM -- \"Named Pipe\" --\u003e C1\n    CM -- \"Named Pipe\" --\u003e C2\n    CM -- \"Named Pipe\" --\u003e C3\n    CM -. \"auto-switch\u003cbr/\u003eif busy\" .-\u003e C1\n    CM -. \"shell routing\" .-\u003e C2\n```\n\n## Install\n\nNo global install is required — `npx` fetches and runs splashshell on demand. The only prerequisite is the [.NET 9 Desktop Runtime](https://dotnet.microsoft.com/download/dotnet/9.0) (the package bundles a ~5.6 MB native `splash.exe` that needs it).\n\n\u003e The `@latest` tag is important: without it, npx will happily keep reusing a stale cached copy even after a new version ships.\n\n### Claude Code\n\n```bash\nclaude mcp add-json splash -s user '{\"command\":\"npx\",\"args\":[\"-y\",\"splashshell@latest\"]}'\n```\n\n### Claude Desktop\n\nAdd to `%APPDATA%\\Claude\\claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"splash\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"splashshell@latest\"]\n    }\n  }\n}\n```\n\n### Build from source (for development)\n\n```bash\ngit clone https://github.com/yotsuda/splashshell.git\ncd splashshell\ndotnet publish -c Release -r win-x64 --no-self-contained -o ./dist\n```\n\nThe binary is `./dist/splash.exe`. Use the absolute path instead of the `npx` command in your MCP config.\n\n## Tools\n\n### Shell tools\n\n| Tool | Description |\n|------|-------------|\n| `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. |\n| `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`. |\n| `wait_for_completion` | Block until busy consoles finish and retrieve cached output (use after a command times out). |\n\nStatus lines include the console name, shell family, exit code, duration, and current directory:\n\n```\n✓ #12345 Sapphire (bash) | Status: Completed | Pipeline: ls /tmp | Duration: 0.6s | Location: /tmp\n```\n\nEach MCP tool call also drains:\n\n- **Cached results** from any console whose timed-out command has since finished\n- **Closed console notifications** when a console window has been closed since the last call\n\n### File tools\n\nClaude Code–compatible file primitives, useful when the MCP client doesn't already provide them.\n\n| Tool | Description |\n|------|-------------|\n| `read_file` | Read a file with line numbers. Supports `offset` / `limit` for paging through large files. Detects binary files. |\n| `write_file` | Create or overwrite a file. Creates parent directories as needed. |\n| `edit_file` | Replace an exact string in a file. Old string must be unique by default; pass `replace_all` to replace every occurrence. |\n| `search_files` | Search file contents with a regular expression. Returns matching lines with file paths and line numbers. Supports `glob` filtering. |\n| `find_files` | Find files by glob pattern (e.g., `**/*.cs`). Returns matching paths. |\n\n## Multi-shell behavior\n\nsplashshell tracks the cwd of every console and can switch transparently between same-shell consoles:\n\n| Scenario | Behavior |\n|---|---|\n| First execute on a new shell | Auto-starts a console; warns so you can verify cwd before re-executing |\n| Active console matches requested shell | Runs immediately |\n| Active console busy, same shell requested | Auto-starts a sibling console **at the source console's cwd** and runs immediately |\n| Switch to a same-shell standby | Prepends `cd` preamble so the command runs in the source cwd, then executes |\n| Switch to a different shell | Warns to confirm cwd (cross-shell path translation is not implemented) |\n| User manually `cd`'d in the active console | Warns so the AI can verify the new cwd before running its next command |\n\nWindow 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.\n\n## Platform support\n\n- **Windows**: ConPTY + Named Pipe (primary target, fully tested)\n- **Linux/macOS**: Unix PTY fallback (experimental)\n\n## How it works\n\nsplashshell 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.\n\nResult: 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.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyotsuda%2Fsplashshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyotsuda%2Fsplashshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyotsuda%2Fsplashshell/lists"}