🚀 Operate on remote systems seamlessly with Claude Code via SSH
An npm package that provides remote versions of Claude Code tools, allowing you to develop, debug, and manage code on remote servers as if they were local.
- Seamless Remote Development - Use Claude Code on remote systems via SSH
- All Claude Tools Available - BashRemote, ReadRemote, WriteRemote, EditRemote, etc.
- SSH Key Integration - Works with your existing
~/.ssh/configand ssh-agent - Zero Configuration - Automatically disables local tools and enables remote ones
- Secure - Uses standard SSH protocols with proper escaping
npm install -g @aiguy110/claude-remoteShell completion is automatically installed! 🎉
The package automatically installs bash and zsh completions during installation. After installing, restart your terminal or run:
# For bash users:
source ~/.bashrc
# For zsh users:
source ~/.zshrcThe completion provides:
- SSH host completion from
~/.ssh/config - Claude CLI argument completion after the target
- Common remote path suggestions
-
Ensure SSH access to your remote system:
# Test SSH connection ssh myserver -
Use claude-remote instead of
claude:# Instead of: claude claude-remote myserver:/path/to/project # Pass any claude arguments claude-remote myserver:/path/to/project --resume claude-remote myserver:/path/to/project -p "help me debug this code"
-
Claude now operates remotely - all file operations, commands, and tools work on the remote system!
- Node.js 18+
- Claude CLI installed (
npm install -g claude-cli) - SSH access to target systems with key-based authentication
- SSH configuration in
~/.ssh/config - ripgrep (
rg) on remote systems (for search functionality)
Note: Password authentication is not currently supported. You must use SSH key-based authentication.
Ensure your ~/.ssh/config has entries for your servers with SSH key authentication:
Host myserver
HostName example.com
User myuser
IdentityFile ~/.ssh/id_rsa
Host production
HostName prod.example.com
User deploy
Port 2222
IdentityFile ~/.ssh/id_ed25519
Important: Only SSH key authentication is supported. Ensure your public key is installed on the remote system (~/.ssh/authorized_keys) and that you can connect without entering a password.
# Work on a project
claude-remote myserver:/var/www/myapp
# Resume a conversation
claude-remote myserver:/home/user/code --resume
# One-shot command
claude-remote production:/opt/service "check the logs for errors"When using claude-remote, Claude has access to these remote tools:
- BashRemote - Execute commands on remote system
- ReadRemote - Read files from remote filesystem
- WriteRemote - Write files to remote filesystem
- EditRemote - Edit remote files with exact string replacement
- MultiEditRemote - Make multiple edits in one operation
- LSRemote - List remote directories
- GlobRemote - Find files by pattern on remote system
- GrepRemote - Search file contents using ripgrep
- Uses your existing SSH keys and agent
- Respects SSH configuration and security settings
- All commands are properly escaped
- No credentials stored or transmitted
- Local tools are disabled when operating remotely
For security, claude-remote automatically removes any previously allowed Remote tool permissions before launching Claude. This prevents permission confusion where users might grant tool permissions in a local directory thinking they apply to the remote directory, only to have those permissions unexpectedly carry over to different SSH targets from the same local directory.
Important: This means that Remote tools cannot be permanently allowed for specific remote directories - you will need to grant permissions each time you use claude-remote. This is a necessary security trade-off to prevent unauthorized access to different remote systems.
SSH Connection Issues:
# Test connectivity
ssh -o ConnectTimeout=5 myserver true
# Check SSH config
ssh -F ~/.ssh/config myserverMissing ripgrep:
# Install on remote system
ssh myserver 'sudo apt install ripgrep' # Ubuntu/Debian
ssh myserver 'brew install ripgrep' # macOSContributions welcome! Please read our contributing guidelines and submit PRs.
MIT License - see LICENSE file for details.