[FEATURE] Remote VM Execution Support for Claude Code

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Currently, Claude Code operates exclusively on the local machine where it's launched. However, many developers work with remote VMs for various reasons (cloud development, resource constraints, team environments, etc.). This limitation prevents Claude Code from being used in these common development workflows.

Proposed Solution

Implement a hybrid architecture where Claude Code maintains separation between AI processing and action execution:

Local Components (Host Machine):

• Claude Code process and UI
• All AI/LLM token generation and inference
• Decision-making and thinking processes
• Command orchestration

Remote Components (Target VM):

• Action execution only (file operations, bash commands)
• File system access
• Process execution
• Environment state queries

Detailed Feature Description

┌─────────────────┐                    ┌──────────────────┐
│   Local Host    │                    │    Remote VM     │
│                 │                    │                  │
│  Claude Code    │  SSH/Protocol      │   Execution      │
│  - AI thinking  │ =================> │   - Run commands │
│  - Decisions    │  Minimal Commands  │   - File ops     │
│  - UI           │ <================= │   - Read files   │
│                 │  Results/Output    │                  │
└─────────────────┘                    └──────────────────┘

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

1. Cloud Development Environments

• Work on AWS EC2, Google Cloud VMs, or Azure instances
• Maintain development environments in the cloud without local setup

1. Resource-Intensive Projects

• Use powerful remote machines for compilation, testing
• Keep laptop resources free while Claude Code thinks locally

1. Consistent Team Environments

• Standardized VMs for all team members
• Avoid "works on my machine" issues

1. Production-Like Development

• Safely work on staging environments
• Test in environments matching production

1. Multi-Platform Development

• Develop on Linux VMs from Windows/Mac
• Cross-platform testing without dual-boot

Additional Context

1. Connection Management

claude-code --remote user@hostname:port
# or
claude-code --remote-config ~/.ssh/config-entry

2. Protocol Options

• Primary: SSH for security and ubiquity
• Alternative: Custom lightweight protocol for optimized performance

3. Configuration Format

{
  "remote": {
    "host": "dev-vm.example.com",
    "user": "developer",
    "port": 22,
    "identity_file": "~/.ssh/id_rsa",
    "working_directory": "/home/developer/projects"
  }
}

4. Safety Features

• Confirm before destructive operations on remote
• Clear indication in UI when in remote mode
• Connection status monitoring

Benefits

1. Performance: AI processing remains fast on local hardware
2. Security: Sensitive context and thinking never transmitted
3. Network Efficiency: Only minimal commands sent over network
4. Compatibility: Works with any SSH-accessible machine
5. Flexibility: No special setup required on remote VMs

Alternative Approaches Considered

• Full Remote Claude Code: Would require sending all AI context over network (slow, insecure)
• VSCode Integration: Limits to VSCode users only
• Custom Agent on Remote: Requires installation and maintenance on every VM

Additional Considerations

• Support for SSH key authentication and password authentication
• Handle network interruptions gracefully
• Ability to sync certain files locally for faster AI context
• Support for SSH tunneling for accessing remote services
• Integration with existing SSH config files

Priority

High - This would unlock Claude Code for a significant portion of professional developers who work primarily on remote systems.