# Teleportation

**Remote approval system for Claude Code**

Approve AI coding changes from your phone—work continues while you're away.

## Overview

Teleportation enables developers to approve Claude Code actions remotely from any device. The system intercepts Claude Code's tool requests via hooks, routes them to a relay API, and displays them in a mobile-friendly UI for instant approval.

## Installation

### Method 1: npm (Recommended)

```bash
# Install globally via npm
npm install -g teleportation-cli

# Verify installation
teleportation --version
```

**Requirements:**
- **Bun >=1.3.0** - [Install Bun](https://bun.sh/docs/installation)
- **Claude Code CLI** - [Install Claude Code](https://claude.ai/code)

> **Note:** While the package uses npm for distribution, it requires Bun as the runtime. Make sure to install Bun first.

### Method 2: Quick Install (curl)

```bash
curl -fsSL https://raw.githubusercontent.com/dundas/teleportation-private/main/scripts/install.sh | bash
```

### Method 3: From Source

**Requirements:** Bun >=1.3.0

```bash
# Install Bun if you haven't already
curl -fsSL https://bun.sh/install | bash

# Clone and install
git clone https://github.com/dundas/teleportation-private.git
cd teleportation-private
bun install
bun link  # Makes 'teleportation' command available globally
```

### Method 4: GitHub Releases

Download the latest release from [GitHub Releases](https://github.com/dundas/teleportation-private/releases/latest) and extract to `~/.teleportation/`.

### Installing Bun

```bash
# macOS, Linux, WSL
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"
```

## Migrating from Node.js Version

If you're upgrading from a previous Node.js version (v0.x):

```bash
# 1. Uninstall old version (if installed globally)
npm uninstall -g @teleportation/cli

# 2. Install Bun
curl -fsSL https://bun.sh/install | bash

# 3. Remove old dependencies
cd /path/to/teleportation
rm -rf node_modules package-lock.json

# 4. Install with Bun
bun install

# 5. Verify installation
./teleportation-cli.cjs --version
```

**Note:** Your hooks and credentials will be preserved during the upgrade.

## Quick Start

```bash
# 1. Install via npm
npm install -g teleportation-cli

# 2. Enable hooks
teleportation on

# 3. Authenticate with your account
teleportation login

# 4. Check status
teleportation status

# 5. Start Claude Code - approvals will be routed to your phone!
```

## Usage

### Basic Commands

```bash
teleportation on          # Enable remote approval hooks
teleportation off         # Disable hooks (local mode)
teleportation status      # Show current configuration
teleportation login       # Authenticate with relay server
teleportation logout      # Clear credentials
teleportation help        # Show all commands
```

### Session Management

```bash
teleportation session list       # List active sessions
teleportation session info       # Show current session details
teleportation session pause      # Pause current session
teleportation session resume     # Resume paused session
```

### Worktree Commands (Multi-session)

```bash
teleportation worktree create <name>   # Create isolated worktree
teleportation worktree list            # List all worktrees
teleportation worktree use <name>      # Switch to worktree
teleportation worktree merge <name>    # Merge worktree changes
```

### Snapshot Commands

```bash
teleportation snapshot create <name>   # Create code snapshot
teleportation snapshot list            # List snapshots
teleportation snapshot restore <name>  # Restore to snapshot
teleportation snapshot diff <name>     # Compare with snapshot
```

## How It Works

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│   Relay API     │────▶│   Mobile UI     │
│   (Your Mac)    │     │   (Cloud)       │     │   (Your Phone)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │ 1. Tool request       │ 2. Push to queue     │
        │    intercepted        │                       │
        │                       │ 3. Display for       │
        │                       │    approval          │
        │                       │                       │
        │ 5. Continue or        │ 4. User approves/    │
        │    block action       │◀───denies            │
        │                       │                       │
```

1. **Intercept**: Claude Code hooks capture tool requests
2. **Route**: Requests are sent to the relay API
3. **Display**: Mobile UI shows pending approvals
4. **Decide**: You approve or deny from your phone
5. **Execute**: Claude Code continues or blocks the action

## Project Structure

```
teleportation/
├── lib/
│   ├── auth/              # Credential encryption & management
│   ├── cli/               # CLI command implementations
│   ├── config/            # Configuration management
│   ├── install/           # Installation logic
│   └── session/           # Session metadata extraction
├── relay/                 # Relay API server
├── mobile-ui/             # Mobile-friendly web UI
├── .claude/
│   └── hooks/             # Claude Code hooks
├── scripts/
│   └── install.sh         # Installation script
├── teleportation-cli.cjs  # Main CLI tool
└── tests/                 # Test suites
```

## Configuration

Configuration is stored in `~/.teleportation/`:

```
~/.teleportation/
├── config.json           # User preferences
├── credentials.enc       # Encrypted credentials
└── bin/
    └── teleportation     # CLI symlink
```

## Documentation

- `RUNBOOK.md` - What must be running (local/prod) + smoke checks
- `docs/E2E_TEST_PLAN.md` - End-to-end test plan and minimum regression matrix
- `DEPLOYMENT_GUIDE.md` - Fly.io / Cloudflare deployment steps
- `CHANGELOG.md` - Versioned change history

Environment variables:
- `TELEPORTATION_RELAY_URL` - Custom relay server URL
- `TELEPORTATION_API_KEY` - API key for authentication

## Self-Hosting

Want to run your own relay server?

```bash
cd relay
cp .env.example .env
# Edit .env with your configuration
bun install
bun start
```

See [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) for full deployment instructions.

## Development

```bash
# Install dependencies
bun install

# Run tests
bun test

# Run relay server locally
bun run dev:relay

# Run mobile UI locally
bun run dev:mobile

# Run everything
bun run dev:all
```

## Security

- **End-to-end encryption**: Credentials encrypted with AES-256
- **OAuth authentication**: Secure login via Google/GitHub
- **Multi-tenant isolation**: Your data is isolated from other users
- **Privacy-preserving**: Session existence not revealed to unauthorized users

## Known Limitations

### Session Registry Race Condition

The remote session registry uses file-based storage (`~/.teleportation/remote-sessions/sessions.json`). There is a theoretical race condition if multiple processes attempt to register the same session ID simultaneously. The check for existing sessions and the save operation are not atomic.

**Impact**: This is an acceptable limitation for the current single-user CLI use case.

**Future mitigation**: Future versions may implement file locking (e.g., using `proper-lockfile` package) or migrate to a database (e.g., SQLite) for multi-user or concurrent scenarios.

## License

MIT

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## Support

- [GitHub Issues](https://github.com/dundas/teleportation-private/issues)
- [Documentation](https://github.com/dundas/teleportation-private/wiki)