tinyagent/README.md

Connect your local shell to any device - access your dev environment from anywhere

# Tinyagent

Connect your local shell to any device - access your dev environment from anywhere.

## Installation

```bash
npm install -g tinyagent
```

## Quick Start

1. Start tinyagent (auto-generates session ID):
```bash
tinyagent
```

Or specify your own session ID:
```bash
tinyagent my-session
```

2. Scan the QR code with the Tinyagent mobile app OR enter the session ID manually

3. Your local terminal is now accessible from your phone!

**Bonus**: If you have Claude CLI installed, it will automatically start Claude for you! Claude will be able to see and interact with your terminal session.

## Features

- 🔐 Secure WebSocket connection through relay servers
- 📱 Full terminal access from mobile devices
- 🌐 HTTP tunneling - access your local dev servers from anywhere
- ⌨️ Bidirectional typing - type from computer or phone
- 📏 Smart terminal resizing based on device
- 🚀 Zero configuration required

## Usage

### Basic connection (auto-generates session ID):
```bash
tinyagent
```

### Connect with specific session ID:
```bash
tinyagent my-session
# or
tinyagent --session-id my-session
```

### Use a custom relay server:
```bash
tinyagent --relay ws://localhost:8080
```

### Specify a custom shell:
```bash
tinyagent --shell /bin/zsh
```

### Disable Claude auto-start:
```bash
tinyagent --no-claude
```

### Advanced: Run a server alongside your shell
```bash
tinyagent -c "npm run dev" -p 3000
```

This runs a dev server in parallel with your shell session (legacy feature - HTTP tunneling now auto-detects running servers).

### All Options:
- `[sessionId]` - Session ID as first argument (optional, auto-generated if not provided)
- `--session-id <id>` - Session ID (alternative to positional argument)
- `-r, --relay <url>` - Relay server URL (default: wss://relay.tinyagent.app)
- `-s, --shell <shell>` - Shell to use (default: $SHELL or /bin/bash)
- `-c, --command <cmd>` - Run a server command in parallel (legacy - auto-detection preferred)
- `-p, --port <port>` - Port for the server command (default: 3000)
- `--no-tunnel` - Disable localtunnel integration
- `--no-claude` - Do not auto-start Claude CLI
- `-v, --verbose` - Show detailed debug output
- `-V, --version` - Show version number
- `-h, --help` - Show help

## HTTP Tunneling

Tinyagent automatically detects and exposes your local development servers! No configuration needed.

When you have servers running on common ports (3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 9000), you'll see:

```
[HTTP] Exposing ports: 3000, 5173
[HTTP] Access your dev server at:
  https://my-session-3000.tinyagent.app/
  https://my-session-5173.tinyagent.app/
```

Access your local dev servers from any browser - perfect for testing on mobile devices!

## Environment Variables

You can set these environment variables to customize default behavior:

- `RELAY_URL` - Default relay server URL (instead of using `-r` flag each time)
- `SHELL` - Default shell to use (automatically detected from your system)

Example:
```bash
export RELAY_URL=ws://localhost:8080
tinyagent
```

## Security

- All connections are routed through relay servers - your machine is never directly exposed
- Session IDs are private - only those with the ID can connect
- Connections are encrypted with WSS (WebSocket Secure)

## Troubleshooting

### Debug Mode
If you're experiencing issues, run with verbose output:
```bash
tinyagent -v
# or
tinyagent --verbose
```

This will show:
- WebSocket connection details
- Terminal resize events
- Input source tracking (local vs mobile)
- HTTP port detection

### Common Issues

**Claude not starting automatically?**
- Make sure Claude CLI is installed and in your PATH
- Try running `which claude` to verify installation
- Use `--no-claude` to disable auto-start

**Dev server not accessible?**
- Ensure your server is running on a standard port (3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 9000)
- Check that the server is bound to `localhost` or `0.0.0.0`, not just `127.0.0.1`
- Look for the `[HTTP] Exposing ports:` message in the output

## Learn More

- Website: https://tinyagent.app
- Documentation: https://docs.tinyagent.app
- Mobile App: Available on App Store and Google Play

## License

MIT