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: Quick Install (curl)

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

Method 2: From Source (Recommended)

Requirements: Bun >=1.3.0

# 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 3: GitHub Releases

Download the latest release from GitHub Releases and extract to ~/.teleportation/.

Requirements

• Bun >=1.3.0 (JavaScript runtime)
• Claude Code CLI installed

Installing Bun

# 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):

# 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

# 1. Enable hooks
teleportation on

# 2. Authenticate with your account
teleportation login

# 3. Check status
teleportation status

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

Usage

Basic Commands

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

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)

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

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

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?

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

See DEPLOYMENT_GUIDE.md for full deployment instructions.

Development

# 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

License

MIT

Contributing

See CONTRIBUTING.md for guidelines.

Support

• GitHub Issues
• Documentation