shell-mirror/README.md

Access your Mac shell from any device securely. Perfect for mobile coding with Claude Code CLI, Gemini CLI, and any shell tool.

# Shell Mirror

**Access your Mac terminal from any device, securely.** Perfect for mobile coding with Claude Code CLI, Gemini CLI, and any shell tool.

---

## What is Shell Mirror?

Shell Mirror lets you access your Mac terminal from any web browser on any device (phone, tablet, laptop). It uses WebRTC for fast, peer-to-peer terminal mirroring with Google OAuth 2.0 authentication to keep your terminal secure.

### Key Features

✅ **Secure Access** - Google OAuth 2.0 authentication
✅ **WebRTC Connection** - Fast, direct peer-to-peer terminal mirroring
✅ **Multiple Sessions** - Create and manage multiple terminal sessions
✅ **Dashboard** - Visual dashboard to manage connected agents and sessions
✅ **Mobile-Friendly** - Optimized for mobile coding (perfect for AI coding tools)
✅ **NPM Package** - Easy installation via `npm install -g shell-mirror`
✅ **Auto-Start** - Mac agent auto-starts and registers with cloud server

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      User's Browser                          │
│              (https://shellmirror.app)                       │
│         ┌──────────────────────────────────────┐            │
│         │  Dashboard  │  Terminal Interface    │            │
│         └──────────────────────────────────────┘            │
└────────────────────┬────────────────────────────────────────┘
                     │
          Google OAuth 2.0 Authentication
                     │
    ┌────────────────▼────────────────────────────┐
    │   Heroku WebSocket Signaling Server         │
    │  (wss://shell-mirror-[...].herokuapp.com)   │
    │                                              │
    │  • WebRTC signaling (SDP/ICE exchange)      │
    │  • Agent discovery & registration           │
    │  • Dashboard real-time updates              │
    └────────────────┬────────────────────────────┘
                     │
         WebSocket Connection (both ways)
                     │
    ┌────────────────▼────────────────────────────┐
    │        Mac Agent (User's Computer)          │
    │                                              │
    │  • Auto-starts on login                     │
    │  • Registers with cloud server              │
    │  • Manages multiple terminal sessions       │
    │  • WebRTC peer connection to browser        │
    └─────────────────────────────────────────────┘
                     │
              Terminal Sessions
                     │
              ┌──────┴──────┐
              │   Terminal   │
              │   (node-pty) │
              └─────────────┘
```

### Components

1. **Frontend (TMDHosting)**: Static website at https://shellmirror.app
2. **WebSocket Server (Heroku)**: Node.js signaling server for WebRTC
3. **PHP Backend (TMDHosting)**: Agent registration and authentication APIs
4. **Mac Agent**: Local terminal mirroring agent (npm package)
5. **Dashboard**: Real-time agent and session management interface

---

## 🚀 Quick Start

### For Users (NPM Package)

```bash
# Install globally
npm install -g shell-mirror

# Run setup wizard (configures Google OAuth)
shell-mirror setup

# Start the agent
shell-mirror start

# Access from browser
# Visit: https://shellmirror.app
```

### For Developers (Local Development)

```bash
# Clone repository
git clone https://github.com/karmalsky/shell-mirror.git
cd terminal-mirror

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your Google OAuth credentials

# Start local WebSocket server
npm start

# Access at http://localhost:3000
```

---

## 🔐 Google OAuth Setup

Shell Mirror requires Google OAuth 2.0 credentials:

1. **Google Cloud Console**: https://console.cloud.google.com/
2. **Create OAuth Client ID**:
   - Application type: **Web application**
   - Authorized JavaScript origins: `https://shellmirror.app`
   - Authorized redirect URIs: `https://shellmirror.app/auth/google/callback`
3. **Copy credentials** to your `.env` file or provide during `shell-mirror setup`

For detailed OAuth setup instructions, see the old README in `old_md/README_old.md` (lines 66-98).

---

## 📱 Usage

### Access Your Terminal

1. **Visit**: https://shellmirror.app
2. **Login** with Google account
3. **Dashboard** shows your connected Mac agents
4. **Connect** to start a terminal session

### Multiple Terminal Sessions

- **Create new session**: Click "New Terminal Session" in dashboard
- **Resume session**: Select from existing sessions list
- **Switch sessions**: Use session dropdown in terminal interface
- **Manage sessions**: View active sessions, close inactive ones

### Mac Agent Commands

```bash
shell-mirror start          # Start agent
shell-mirror stop           # Stop agent
shell-mirror restart        # Restart agent
shell-mirror status         # Check status
shell-mirror setup          # Run setup wizard
```

---

## 🛠️ Development & Deployment

### Project Structure

```
terminal-mirror/
├── server.js              # WebSocket signaling server
├── auth.js                # Google OAuth configuration
├── lib/                   # CLI and agent management
│   ├── auto-start.js      # Mac agent auto-start logic
│   ├── setup-wizard.js    # Interactive setup
│   └── ...
├── mac-agent/             # Mac terminal mirroring agent
│   ├── agent.js           # Main agent (WebRTC + sessions)
│   └── http-agent.js      # HTTP polling fallback
├── public/                # Frontend files
│   ├── index.html         # Landing page
│   └── app/               # Dashboard and terminal UI
├── heroku/                # Heroku WebSocket server deployment
└── php-backend/           # PHP APIs for agent registration
```

### Deployment

```bash
# Deploy WebSocket server to Heroku
./deploy-heroku.sh

# Deploy website/PHP backend to TMDHosting
node deploy-php.cjs

# Publish NPM package (user must run manually per CLAUDE.md)
./publish.sh
```

For detailed deployment instructions, see `DEPLOYMENT-PUBLISHING-GUIDE.md`.

---

## 📊 Monitoring & Logs

### Check Status
```bash
./status.sh     # Check all services
```

### View Logs
```bash
# Heroku WebSocket server
heroku logs --tail -a shell-mirror

# PHP backend (web)
https://shellmirror.app/debug.html

# Local logs
tail -f server-debug.log
```

For complete operations guide, see `OPERATIONS.md`.

---

## 📚 Documentation

- **README.md** (this file) - Overview and quick start
- **OPERATIONS.md** - Monitoring, logs, troubleshooting
- **QUICK-REFERENCE.md** - Fast command reference
- **DEPLOYMENT-PUBLISHING-GUIDE.md** - Deployment procedures
- **TECHNICAL-NOTES.md** - macOS firewall behavior notes
- **ANALYTICS_SETUP.md** - Google Analytics and Clarity setup
- **old_md/** - Archived planning documents and old README

---

## 🔍 Technical Details

### Multiple Sessions Implementation

Shell Mirror supports multiple persistent terminal sessions per user:

- **SessionManager class** in `mac-agent/agent.js` (line 158)
- **Dashboard UI** for creating/managing sessions
- **Session persistence** across browser disconnects
- **Resource limits**: Max 10 sessions per agent
- **Auto-cleanup**: Sessions idle > 24 hours are terminated

### WebRTC Connection

- **Signaling**: Via Heroku WebSocket server
- **Data Channel**: For terminal I/O (fast, low latency)
- **ICE/STUN/TURN**: Automatic NAT traversal
- **Fallback**: HTTP polling if WebRTC fails

### Security

- **Authentication**: Google OAuth 2.0
- **Authorization**: Session-based access control
- **Encryption**: WSS (WebSocket Secure) + HTTPS
- **No credentials stored**: Secure token-based auth

---

## 🌐 Production URLs

- **Website**: https://shellmirror.app
- **WebSocket Server**: https://shell-mirror-30aa5479ceaf.herokuapp.com
- **NPM Package**: https://www.npmjs.com/package/shell-mirror
- **Debug Dashboard**: https://shellmirror.app/debug.html

---

## 📦 NPM Package

**Current Version**: 1.5.74

```bash
# Install
npm install -g shell-mirror

# Usage
shell-mirror --help
```

Package includes:
- Mac agent with WebRTC support
- Interactive setup wizard
- Auto-start configuration
- CLI for agent management

---

## 🐛 Troubleshooting

### Agent Not Connecting

```bash
# Check agent status
shell-mirror status

# View logs
tail -f ~/.shell-mirror/agent.log

# Restart agent
shell-mirror restart
```

### WebSocket Server Issues

```bash
# Check server health
curl https://shell-mirror-30aa5479ceaf.herokuapp.com/health

# View Heroku logs
heroku logs --tail -a shell-mirror
```

### Browser Connection Issues

- **Debug interface**: https://shellmirror.app/debug-connection.html
- **Check browser console**: F12 → Console tab
- **Verify authentication**: https://shellmirror.app/api/auth/status

For detailed troubleshooting, see `OPERATIONS.md`.

---

## 🤝 Contributing

This is currently a personal project. For bug reports or feature requests, please check the GitHub issues.

---

## 📄 License

MIT

---

## 🎯 Use Cases

- **Mobile Coding**: Use Claude Code CLI or Gemini CLI from your phone
- **Remote Access**: Access your development environment from anywhere
- **Pair Programming**: Share terminal sessions with collaborators
- **Quick Fixes**: Make quick changes on the go without VPN/SSH setup
- **Multi-Device Workflow**: Seamlessly switch between devices

---

*Last Updated: 2025-01-26*
*Version: 1.5.74*