{
  "markdown": "# mcp-reconnect\n\nAutomated MCP server reconnection for Claude Code sessions running in tmux.\n\n![demo](demo/demo.gif)\n\n> *Real demo against Claude Code v2.1.150 — actual `/mcp` menu, actual cursor navigation, actual reconnect. See `demo/README.md` for how to rebuild.*\n\nCurrent version: v1.2.0\n\nClaude Code has no programmatic API for MCP reconnect — the only way is through the interactive `/mcp` menu. This tool automates that entire sequence via `tmux send-keys`, handling single machines, multi-session environments, and remote hosts over SSH.\n\n## The Problem\n\n**Building MCP servers, you iterate.** Edit the server code, restart the process, switch to your Claude Code session, `/mcp` → arrow down → Enter to reconnect, type the prompt you were working on. Every cycle. This is exactly the loop mcp-reconnect was built for — let the agent reconnect itself so you stay in flow instead of context-switching to drive a menu.\n\nThe same pain shows up at fleet scale: deploying new MCP server code or restarting server processes drops the connection on every active Claude Code session. With multiple sessions across multiple machines, manually walking `/mcp` → Reconnect on each one becomes the bottleneck.\n\nmcp-reconnect handles both cases: one session, your session, every session — local or over SSH.\n\n## The Solution\n\n`mcp-reconnect` drives the `/mcp` menu programmatically through tmux:\n\n```\nEscape        →  stop active generation\n/mcp + Enter  →  submit the /mcp slash command\nEnter         →  enter the menu\nDown + Enter  →  select \"Reconnect\" (2nd option)\n<prompt>      →  continuation message so Claude resumes work\n```\n\n## Install\n\n### Standalone script\n\n```bash\ngit clone https://github.com/palios-taey/mcp-reconnect.git\ncd mcp-reconnect\nsudo make install\n```\n\nThis installs `mcp-reconnect` to `/usr/local/bin`. To customize:\n\n```bash\nsudo make install PREFIX=/opt/local\n```\n\n### Claude Code plugin\n\n```\n/plugin marketplace add palios-taey/mcp-reconnect\n/plugin install mcp-reconnect@mcp-reconnect\n```\n\nOr test locally:\n\n```bash\nclaude --plugin-dir ./path/to/mcp-reconnect\n```\n\n## Usage\n\n```bash\n# Reconnect all Claude Code tmux sessions on this machine\nmcp-reconnect\n\n# Reconnect specific sessions by name\nmcp-reconnect weaver architect\n\n# Reconnect all sessions on a remote host\nmcp-reconnect --remote myserver\n\n# Reconnect a specific session on a remote host\nmcp-reconnect --remote myserver weaver\n\n# Preview what would happen (no keys sent)\nmcp-reconnect --dry-run\n\n# Select menu items by visible text\nmcp-reconnect --path Reconnect\nmcp-reconnect --path taeys-hands --path Reconnect\nmcp-reconnect --path taeys-hands --path \"Show details\"\n```\n\n### Calling from within Claude Code\n\nWhen `mcp-reconnect` is called from a Claude Code session itself (e.g., during a deploy script), it must run detached with a delay — otherwise the Escape keystroke kills the calling session before the bash tool returns.\n\n```bash\nnohup mcp-reconnect --delay 10 &>/dev/null & disown\n```\n\nThe `--delay` flag waits N seconds before sending any keystrokes, giving the calling session time to finish its tool execution.\n\n## Options\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--remote HOST` | — | Target a remote machine via SSH |\n| `--delay N` | `0` | Wait N seconds before starting (for detached use) |\n| `--settle-esc N` | `5` | Seconds to wait after Escape |\n| `--settle-mcp N` | `2` | Seconds to wait after `/mcp` submit |\n| `--settle-select N` | `5` | Seconds to wait after selecting Reconnect |\n| `--path LABEL` | — | Select a visible `/mcp` menu label; repeat for submenu paths |\n| `--server NAME` | — | Shorthand for `--path NAME --path Reconnect` |\n| `--message MSG` | *(built-in)* | Override the continuation prompt |\n| `--dry-run` | — | Show actions without sending keys |\n| `--help` | — | Show usage information |\n\n## Path navigation\n\n`--path` selects `/mcp` menu items by matching the visible cursor line, using a fixed-string, case-insensitive substring match. Repeat it to walk through nested menu levels:\n\n```bash\n# Reconnect in Claude Code's single-server menu\nmcp-reconnect --path Reconnect\n\n# Multi-server menu: choose a server, then reconnect it\nmcp-reconnect --path taeys-hands --path Reconnect\n\n# Choose a different action in the server submenu\nmcp-reconnect --path taeys-hands --path \"Show details\"\n```\n\n`--server NAME` remains supported as a backwards-compatible shorthand for `--path NAME --path Reconnect`. `--path` and `--server` are mutually exclusive. `--path` is currently local-only; `--path --remote HOST` exits with a clear error instead of sending keys.\n\n## Requirements\n\n- **tmux** — Claude Code sessions must be running inside tmux\n- **bash** ≥ 4.0 (for `mapfile` and associative arrays)\n- **ssh** — for `--remote` mode, with key-based authentication configured\n\nNo other dependencies. No Redis, no Python, no Node.js.\n\n## Design Decisions\n\nThese constraints were discovered through extensive production testing:\n\n### Parallel local, sequential remote\n\nLocal sessions run in parallel — each targets a different tmux pane, so there's no contention. Remote sessions run sequentially over SSH to avoid connection multiplexing issues.\n\n### Conservative settle times\n\nThe default timings (5s after Escape, 2s after `/mcp`, 5s after Reconnect) are deliberately conservative. Faster timings cause missed keystrokes — the menu doesn't render fast enough, or Claude hasn't fully stopped generating. You can tune these down with `--settle-*` flags, but test carefully.\n\n### Stale process cleanup\n\nConsecutive deploys can spawn duplicate reconnect scripts. The script kills prior instances on startup to prevent keystroke collisions. The cleanup logic excludes its own PID and parent PID to avoid killing the calling shell (a subtle bug discovered during testing — `pgrep -f` matches any process whose command line contains the script name, including the parent shell).\n\n### Detached execution\n\nWhen called from within a Claude Code session — for example, as part of a deploy pipeline — the script must be detached (`nohup ... & disown`) with a delay (`--delay 10`). Without this, the Escape keystroke hits the calling session before its bash tool has returned, breaking the calling session's state.\n\n### Plain Enter, no C-j\n\nKitty keyboard protocol (`C-j`) was tested and found unnecessary. Plain `Enter` via `tmux send-keys` works reliably across terminal emulators.\n\n## How it works\n\n1. **Session detection**: Lists all tmux sessions, checks each pane's `pane_current_command` for `\"claude\"`\n2. **Stale cleanup**: Kills any prior `mcp-reconnect` processes to prevent duplicates\n3. **Key injection**: For each Claude session, sends the exact keystroke sequence to navigate the `/mcp` → Reconnect menu\n4. **Continuation**: After reconnect completes, sends a text prompt so Claude knows MCP is back and resumes work\n\nFor remote hosts, the same logic runs over SSH with the key sequence inlined as a heredoc.\n\n## Integration examples\n\n### MCP server dev loop (the original use case)\n\nWhen you're building an MCP server, the inner loop is: edit server code → restart the server process → reconnect your Claude Code session to pick up the change → continue. `mcp-reconnect` removes the manual `/mcp` navigation step from that loop:\n\n```bash\n# In your shell, after restarting the MCP server process:\nmcp-reconnect <your-tmux-session-name>\n\n# Or have Claude do it for you mid-conversation, since it has shell access:\n# (just ask: \"restart my MCP server and reconnect\")\n# Claude runs:\n#   pkill -f 'my-mcp-server' && sleep 1 && my-mcp-server &\n#   nohup mcp-reconnect --delay 3 <my-session> &>/dev/null & disown\n```\n\nThe `nohup ... & disown` form lets Claude's own session call mcp-reconnect against itself without race conditions — the call returns before Escape hits, then the delayed mcp-reconnect drives the menu in the now-idle pane.\n\nFor testing a new MCP tool: same loop, just substitute your test invocation. Once the tool is wired and connected, mcp-reconnect makes \"reconnect to pick up my code change\" a one-line shell command instead of a context-switch + menu drive.\n\n### Post-deploy hook\n\n```bash\n#!/bin/bash\n# deploy.sh — deploy and reconnect\n\n# ... your deploy logic (git pull, kill MCP servers, etc.) ...\n\n# Reconnect all sessions (detached, with delay)\nnohup mcp-reconnect --delay 10 &>/dev/null & disown\necho \"MCP reconnect scheduled (10s delay)\"\n```\n\n### Multi-machine deploy\n\n```bash\n#!/bin/bash\nHOSTS=(server1 server2 server3)\n\nfor host in \"${HOSTS[@]}\"; do\n    echo \"Deploying to $host...\"\n    ssh \"$host\" \"cd /path/to/repo && git pull && pkill -f 'python3.*server.py'\"\ndone\n\n# Reconnect all machines sequentially\nfor host in \"${HOSTS[@]}\"; do\n    mcp-reconnect --remote \"$host\"\ndone\n```\n\n### Claude Code hook (plugin)\n\nWhen installed as a plugin, `mcp-reconnect` includes a notification hook that detects MCP disconnection events and prompts Claude to reconnect.\n\n## License\n\n[MIT](LICENSE)\n\n## Contributing\n\nIssues and pull requests welcome at [github.com/palios-taey/mcp-reconnect](https://github.com/palios-taey/mcp-reconnect).\n",
  "bytes": 9090,
  "sha": "e01c0a94ae0048ebc39b2eb3f44d44b4073a36c9a164ae0e15589ce8659d1df9",
  "repo_slug": "palios-taey/mcp-reconnect",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_palios_taey_mcp_reconnect_mcp_reconnect_400721f8/readme"
}