Upload README.md with huggingface_hub

README.md

@@ -6,8 +6,19 @@ Terminal access for Claude with two security modes, plus SSH bridge for remote s
 
 - **Local shell** with safe/dangerous command separation
 - **SSH Bridge** - GUI app for secure remote server access
-- **Full visibility** - see every command Claude runs
-- **Instant disconnect** - revoke access anytime
+- **Lift Pen** - Pause Claude's command execution instantly
+- **Sudo support** - Auto-send password for sudo commands (opt-in)
+- **Full visibility** - See every command Claude runs in real-time
+- **Background processes** - Spawn and manage long-running tasks
+- **File operations** - Write files without shell escaping issues
+
+## Quick Start (Pre-built Binaries)
+
+Download from the `release/` folder:
+- `shell-mcp.dll` - MCP server for Claude Desktop
+- `ssh-bridge.exe` - GUI for SSH connections
+
+No build required - just configure Claude Desktop (see below).
 
 ## Components
 
@@ -15,26 +26,33 @@ Terminal access for Claude with two security modes, plus SSH bridge for remote s
 Local Windows terminal access with configurable command allowlists.
 
 ### 2. SSH Bridge (`ssh-bridge.exe`)
-WinForms app that:
-- You authenticate with password (never stored on disk)
+WinForms GUI that:
+- You authenticate with password (held in memory only)
 - Claude sends commands through it
-- You see all commands and output in real-time
-- Click Disconnect to revoke access instantly
+- Real-time output display with syntax highlighting
+- **Lift Pen** button to pause Claude instantly
+- **Sudo** button to enable auto-password for sudo commands
+- **Pin** button to keep window on top
+- Right-click context menu: Copy, Copy All, Clear
 
 ## Installation
 
-### Prerequisites
+### Option 1: Use Pre-built Binaries
+1. Download files from `release/` folder
+2. Configure Claude Desktop (see below)
+
+### Option 2: Build from Source
+
+**Prerequisites:**
 - .NET 8.0 SDK
 - Windows 10/11
 
-### Build
-
 ```bash
 git clone https://github.com/FreeOnlineUser/shell-mcp.git
 cd shell-mcp
 dotnet restore
-dotnet build ShellMcp.csproj
-dotnet build SshBridge.csproj
+dotnet build ShellMcp.csproj -c Release
+dotnet build SshBridge.csproj -c Release
 ```
 
 ### Configure Claude Desktop
@@ -46,18 +64,20 @@ Edit `%APPDATA%\Claude\claude_desktop_config.json`:
   "mcpServers": {
     "shell_safe": {
       "command": "dotnet",
-      "args": ["C:\\path\\to\\shell-mcp.dll"],
+      "args": ["C:\\path\\to\\release\\shell-mcp.dll"],
       "env": {
         "SHELL_MCP_MODE": "safe",
-        "SHELL_MCP_START_DIR": "C:\\your\\workspace"
+        "SHELL_MCP_START_DIR": "C:\\your\\workspace",
+        "SSH_BRIDGE_PATH": "C:\\path\\to\\release\\ssh-bridge.exe"
       }
     },
     "shell_dangerous": {
       "command": "dotnet",
-      "args": ["C:\\path\\to\\shell-mcp.dll"],
+      "args": ["C:\\path\\to\\release\\shell-mcp.dll"],
       "env": {
         "SHELL_MCP_MODE": "dangerous",
-        "SHELL_MCP_START_DIR": "C:\\your\\workspace"
+        "SHELL_MCP_START_DIR": "C:\\your\\workspace",
+        "SSH_BRIDGE_PATH": "C:\\path\\to\\release\\ssh-bridge.exe"
       }
     }
   }
@@ -73,57 +93,99 @@ Edit `%APPDATA%\Claude\claude_desktop_config.json`:
 ### Local Shell
 | Tool | Description |
 |------|-------------|
-| `Shell` | Execute a local command |
+| `Shell` | Execute a local command with optional timeout |
 | `Pwd` | Get current working directory |
-| `ShellInfo` | Show mode and allowed commands |
+| `ShellInfo` | Show mode and list of allowed commands |
 | `ShellBatch` | Run multiple commands in sequence |
 
-### SSH (requires SSH Bridge running)
+### SSH Tools
 | Tool | Description |
 |------|-------------|
 | `SshCommand` | Execute command on remote server |
 | `SshStatus` | Check if SSH Bridge is connected |
-
-## SSH Bridge Usage
-
-1. Run `ssh-bridge.exe`
-2. Enter host, username, and password
-3. Click **Connect**
-4. Window shows all commands Claude runs and their output
-5. Click **Disconnect** anytime to revoke access
-
-Password is held in memory only while connected - never written to disk.
+| `SshPrefill` | Pre-fill connection details and optionally auto-connect |
+| `SshPenStatus` | Check if user has paused execution (pen lifted) |
+| `SshPenDown` | Request to resume execution |
+| `SshAbort` | Send Ctrl+C to abort running command |
+| `SshIsRunning` | Check if a command is currently executing |
+| `SshSetTimeout` | Set timeout for next command (1-3600 seconds) |
+| `SshTail` | Get last 50 lines of terminal output |
+| `SshKillPort` | Kill process listening on a specific port |
+| `SshSpawn` | Start a background process with a trackable name |
+| `SshListSpawned` | List all tracked background processes |
+| `SshKillSpawned` | Kill a background process by name |
+| `SshWriteFile` | Write content to file without shell escaping |
+| `SshAppendFile` | Append content to file without shell escaping |
+
+## SSH Bridge Features
+
+### Lift Pen (Pause Claude)
+Click **Lift Pen** to immediately pause Claude's command execution. Any running command is aborted, and new commands are blocked until you click again to resume. Perfect for:
+- Reviewing what Claude is doing
+- Taking manual control temporarily
+- Emergency stop
+
+### Sudo Support
+Click **Sudo** to enable auto-password entry for sudo commands. When enabled:
+- Claude can run `sudo` commands without prompting
+- Your password is sent automatically when sudo asks
+- Password is only held in memory while connected
+
+### Pin Window
+Click **Pin** to keep the SSH Bridge window always on top.
+
+### Interactive Command Blocking
+The bridge automatically blocks interactive commands that would break the shell:
+- **Editors:** vim, nano, emacs (use `echo` or `SshWriteFile` instead)
+- **Pagers:** less, more (use `cat`, `head`, `tail` instead)
+- **TUI apps:** htop, top (use `top -b -n 1` or `ps aux`)
+- **Databases:** mysql, psql (use `-e` or `-c` flags for queries)
+- **Multiplexers:** tmux, screen (not supported)
+
+Each blocked command shows helpful alternatives.
 
 ## Security Model
 
 ### shell_safe (approve once)
 Read-only and build commands:
-- `dir`, `ls`, `type`, `cat`, `pwd`, `cd`
-- `git status`, `git log`, `git diff`, `git branch`
-- `dotnet build`, `dotnet run`, `dotnet test`
-- `npm install`, `npm run`, `npm test`
+- `dir`, `ls`, `type`, `cat`, `head`, `tail`, `find`, `grep`, `pwd`, `cd`, `tree`
+- `echo`, `date`, `time`, `whoami`, `hostname`
+- `git status`, `git log`, `git diff`, `git branch`, `git remote`, `git fetch`, `git show`
+- `dotnet build`, `dotnet run`, `dotnet test`, `dotnet restore`
+- `npm install`, `npm run`, `npm test`, `npm list`, `npm ci`
+- `node --version`, `yarn install`, `yarn build`, `yarn test`
 
 ### shell_dangerous (approve each time)
 Modifying commands:
 - `del`, `rm`, `rmdir`, `move`, `copy`, `mkdir`
-- `git push`, `git commit`, `git reset`
-- `taskkill`
+- `git push`, `git pull`, `git merge`, `git rebase`, `git reset`, `git commit`, `git add`
+- `taskkill`, `shutdown`
+- `npm install -g`, `npm uninstall`
 
 ### Always blocked
-- `format`, `diskpart`, `regedit`
+- `format`, `diskpart`, `reg`, `regedit`
 - `net user`, `net localgroup`
-- `rm -rf /`, `del /s /q c:\`
+- `powershell -enc`, `rm -rf /`, `del /s /q c:\`
+
+### SSH Bridge Security
+- Password held in memory only - never written to disk
+- Lift Pen for instant pause
+- Disconnect for instant revoke
+- All commands visible in real-time
+- Sudo disabled by default
+
+## Output Handling
 
-### SSH Bridge
-- You authenticate manually each session
-- You see every command in real-time
-- Disconnect button = instant revoke
-- No password persistence
+- Large outputs are automatically truncated (last 150 lines returned to Claude)
+- Maximum 500KB per response
+- Real-time streaming display in SSH Bridge window
+- ANSI escape codes stripped for clean output
 
 ## Dependencies
 
 - [ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol) - MCP SDK for .NET
 - [SSH.NET](https://www.nuget.org/packages/SSH.NET) - SSH client library
+- [BouncyCastle](https://www.nuget.org/packages/BouncyCastle.Cryptography) - Cryptography (SSH.NET dependency)
 
 ## License