aigo

Stream AI coding assistants to the web - run Claude Code or Cursor Agent remotely from any device.

aigo wraps Claude Code or Cursor Agent in a tmux session and streams it to your browser via WebSocket, letting you access your AI coding sessions from your phone, tablet, or any browser.

Installation

Install aigo from npm:

``bash


Install globally

npm install -g aigo

Or use npx (no installation required)

npx aigo claude
`

Package: npmjs.com/package/aigo

Quick Start

`bash


Start Claude Code with web access (ngrok tunnel enabled by default)

aigo claude

Or start Cursor Agent

aigo cursor

Local only (no tunnel)

aigo --tunnel none claude
`

Requirements

- Node.js 18+
- tmux installed and in PATH
- Claude Code CLI installed (claude command) - for Claude Code support
- Cursor Agent CLI installed (agent command) - for Cursor support
- ngrok (default for remote access) - sign up at ngrok.com
- cloudflared (alternative to ngrok) - free, no signup required

$3

`bash


macOS

brew install tmux

Ubuntu/Debian

sudo apt install tmux

Arch Linux

sudo pacman -S tmux
`

$3

`bash


macOS

brew install ngrok

Or download from https://ngrok.com/download

Then authenticate (required)

ngrok config add-authtoken YOUR_TOKEN
`

$3

cloudflared is a free alternative to ngrok that doesn't require signup:

`bash


macOS

brew install cloudflared

Ubuntu/Debian

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

Or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

`

No authentication required for quick tunnels (trycloudflare.com).

$3

`bash


Install Cursor CLI

curl https://cursor.com/install -fsS | bash

Authenticate (required before first use)

agent login

Or use API key for headless/automation

export CURSOR_API_KEY=your_api_key_here
`

Usage

`
aigo [options] claude [claude-args]
aigo [options] cursor [cursor-args]
aigo [options] agent [agent-args]
aigo [options] --attach

Tools:
claude Use Claude Code CLI
cursor, agent Use Cursor Agent CLI

Options:
--port, -p Web server port (default: 3000, auto-selects if busy)
--session, -s tmux session name (default: claude-code or cursor-agent)
--tunnel, -t Tunnel: ngrok, cloudflared, none (default: ngrok)
--attach, -a Attach to existing tmux session
--password, -P Custom password (default: auto-generated 6-char)
--timeout, -T Lock screen after inactivity (default: 0=disabled)
--exit-timeout, -E Exit session after inactivity (default: 0=disabled)
--help, -h Show help
--version, -v Show version
`

$3

`bash


Claude Code Examples (ngrok tunnel by default)

aigo claude # Start Claude with ngrok tunnel
aigo --tunnel none claude # Local only (no tunnel)
aigo -p 8080 -s myproject claude # Custom port and session
aigo claude --model sonnet # Pass args to Claude

Cursor Agent Examples

aigo cursor # Start Cursor Agent with ngrok tunnel
aigo --tunnel cloudflared cursor # Use cloudflared instead of ngrok
aigo -p 8080 -s myproject cursor # Custom port and session
aigo cursor --model gpt-5 # Pass args to Cursor Agent

General Examples

aigo --attach myproject # Attach to existing tmux session
aigo -P mypass123 claude # Custom password
aigo -T 15 -E 30 cursor # 15min lock, 30min exit timeout
aigo -T 0 -E 0 claude # Disable timeouts (default behavior)

Run multiple sessions (ports auto-selected)

aigo -s project-a claude # Gets port 3000
aigo -s project-b cursor # Gets port 3001 (auto)
`

Configuration

All defaults can be customized by editing lib/config.js:

`javascript
export const config = {
// Server Settings
defaultPort: 3000,
defaultTunnel: 'ngrok', // 'ngrok', 'cloudflared', or 'none'

// Session Timeouts (minutes, 0 = disabled)
lockTimeout: 0, // Lock screen after inactivity (default: disabled)
exitTimeout: 0, // Exit session after inactivity (default: disabled)

// Tool Settings
defaultTool: 'claude', // 'claude' or 'cursor'

// Security Settings
passwordLength: 6,
tokenBytes: 2, // URL token length (hex = 2x chars)

// ... more options
};
`

Tunnel Options

aigo supports two tunnel providers for remote access:

| Feature | ngrok | cloudflared |
|---------|-------|-------------|
| Signup required | Yes | No |
| Free tier limits | 1 tunnel, rate limits | Unlimited quick tunnels |
| Custom domains | Paid plans | Requires Cloudflare account |
| URL format | .ngrok-free.app | .trycloudflare.com |
| Authentication | Required (authtoken) | Not required |

Recommendation: Use cloudflared for quick testing (no signup needed). Use ngrok if you need stable URLs or have an existing account.

`bash


Use cloudflared (no signup required)

aigo --tunnel cloudflared claude

Use ngrok (default, requires signup)

aigo claude

Local only (no tunnel)

aigo --tunnel none claude
`

How It Works

1. aigo creates a tmux session and runs claude or agent inside it
2. A local web server starts, serving an xterm.js terminal
3. The server attaches to the tmux session via node-pty
4. Your browser connects via WebSocket for real-time terminal streaming
5. A tunnel (ngrok or cloudflared) creates a public HTTPS URL for remote access

`
┌────────────────────────────────────────┐
│ aigo - Claude Code Web Terminal │
├────────────────────────────────────────┤
│ Session: claude-code │
│ Local: http://localhost:3000 │
│ Tunnel: https://abc123.ngrok.io │
│ Password: Xk7mNp │
│ Timeout: lock:off exit:off │
└────────────────────────────────────────┘

Access URL:
https://abc123.ngrok.io/t/a1b2c3d4...
`

Cursor vs Claude Code

| Feature | Claude Code | Cursor Agent |
|---------|-------------|--------------|
| Command | aigo claude | aigo cursor |
| CLI Binary | claude | agent |
| Authentication | Claude API key / OAuth | Browser login or CURSOR_API_KEY |
| Models | Claude models | Multiple (GPT-5, Claude, etc.) via subscription |
| Session Default | claude-code | cursor-agent |

When to use Cursor: If you have a Cursor subscription but don't have direct Claude API access, Cursor Agent provides an alternative way to access AI coding assistance remotely.

Security

aigo uses multiple layers of security:

1. URL Token - A random 4-character token in the URL path (/t/)
2. Password - A 6-character alphanumeric password (or custom password via -P)
3. Brute-Force Protection - Progressive delays and lockout after failed attempts
4. Session Lock - Screen locks after inactivity (disabled by default, enable with -T )
5. Auto Exit - Session terminates after inactivity (disabled by default, enable with -E )

Security features:
- Token required in URL (403 Forbidden without it)
- Password required before terminal access
- Password uses unambiguous characters (no 0/O, 1/l/I)
- Brute-force protection with progressive delays (see below)
- Lock screen requires re-entering password after inactivity (when enabled)
- Session auto-terminates and kills tmux after extended inactivity (when enabled)
- HTTPS via tunnel (encrypted in transit)

$3

aigo automatically protects against password brute-force attacks with:
- Progressive delays after 5 failed attempts
- IP-based tracking that persists across page refreshes
- 15-minute lockout after 10 failed attempts

| Attempt | Behavior |
|---------|----------|
| 1-4 | Instant response |
| 5 | 1 second wait (input disabled, countdown shown) |
| 6 | 2 second wait |
| 7 | 4 second wait |
| 8 | 8 second wait |
| 9 | 16 second wait |
| 10+ | IP locked out for 15 minutes |

After 5 failed attempts, the password input is disabled and a countdown timer shows the remaining wait time. After 10 failed attempts, the IP address is locked out for 15 minutes - refreshing the page won't reset the counter.

Configure in lib/config.js:
`javascript
maxAuthAttempts: 10, // Lock out IP after this many failures
authDelayThreshold: 5, // Start delays after this many failures
authBaseDelayMs: 1000, // Base delay (doubles each attempt)
authLockoutMins: 15, // Lockout duration after max attempts
`

Recommendations:
- Use HTTPS (both ngrok and cloudflared provide this automatically)
- Don't share your access URL or password publicly
- Use strong custom passwords for sensitive sessions
- Enable timeouts (-T 15 -E 30) for shared or sensitive environments

Session Timeouts

aigo has two optional timeout mechanisms (both disabled by default for persistent sessions):

$3


When enabled with -T , the session locks after the specified period of no interaction (mouse movement, typing, etc.) and requires password re-entry. The WebSocket connection stays open, so you don't lose any terminal state.

$3

When enabled with -E , the session completely terminates after the specified period of total inactivity (no user login or interaction):
- The tmux session is killed
- Claude Code / Cursor Agent is stopped
- The server exits

Enable timeouts for security in shared environments: aigo -T 15 -E 30 claude

Browser Notifications

aigo can send browser notifications when:
- The AI assistant is waiting for input
- The WebSocket connection is lost

Notifications are only sent when the browser tab is not active. Allow notifications when prompted for the best experience.

Mobile Controls

When accessing aigo from a mobile device (phone or tablet), control buttons appear at the bottom of the screen:

| Button | Action | Description |
|--------|--------|-------------|
| History | View Buffer | Opens a fullscreen modal showing the terminal scrollback buffer (useful when TUI scrolling doesn't work on mobile) |
| Mode | Shift+Tab | Toggle between chat/edit modes in Claude Code or switch modes in Cursor Agent |
| Enter | Enter | Send Enter key to confirm prompts or submit input |
| Stop | Ctrl+C | Interrupt the current operation (stop running commands or cancel AI responses) |

These buttons are useful because mobile keyboards don't easily support modifier key combinations like Ctrl+C or Shift+Tab.

$3

The History button is particularly useful on mobile devices where terminal scrolling often doesn't work properly with TUI applications like Claude Code or Cursor Agent. When pressed:

1. Opens a fullscreen modal overlay
2. Captures the entire terminal scrollback buffer from tmux
3. Displays the content in a scrollable view with ANSI codes stripped for readability
4. Press Close or the ESC key to return to the terminal

This provides an alternative way to review previous AI responses and conversation history without relying on terminal scrolling.

The buttons are automatically shown based on:
- Touch screen capability
- Mobile user agent detection
- Screen width (768px or less)
- Coarse pointer media query (touch screens)

Running Persistently

To keep aigo running indefinitely (even after closing your terminal), run it inside tmux or use a process manager:

`bash


Run aigo inside its own tmux session

tmux new-session -d -s aigo-server 'aigo claude'

Attach to check status

tmux attach -t aigo-server

Or use pm2 for auto-restart on crash

pm2 start "aigo claude" --name aigo-session
`

When the aigo server stays running, your tunnel URL remains stable and you can return to the same URL anytime. Note: cloudflared quick tunnel URLs change on restart, while ngrok URLs persist within a session.

Auto Port Selection

If the default port (3000) or your specified port is already in use, aigo automatically finds the next available port:

`
⚠ Port 3000 in use, using port 3001 instead
`

This allows running multiple aigo sessions simultaneously without manual port management.

Exiting and Cleanup

aigo provides different exit behaviors depending on how you terminate the session:

$3

| Action | tmux Session | Server | Web Clients |
|--------|-------------|--------|-------------|
| Web Exit button | Killed | Stopped | Shows "Session Ended" |
| Console Ctrl+C | Persists | Stopped | Disconnected |
| Inactivity timeout | Killed | Stopped | Shows "Session Expired" |

$3

Click the Exit button in the top-right corner of the web interface to:
1. Show a confirmation dialog
2. Kill the PTY process
3. Kill the tmux session
4. Close all WebSocket connections
5. Shut down the aigo server
6. Exit the process

Result: Everything is cleaned up - tmux session, server, and process all terminate. The web client shows a "Session Ended" message.

This is useful when you're completely done with a session and want to free all resources.

$3

When you press Ctrl+C on the terminal running aigo:
1. The web server stops
2. The tunnel closes (if running)
3. The tmux session keeps running!
4. Connected web clients are disconnected

Result: Server stops but the tmux session persists. This is useful when you want to temporarily stop web access but keep the AI session alive.

Re-attach later:

`bash


Via aigo (starts new web server for existing session)

aigo --attach claude-code
aigo --attach cursor-agent

Or directly with tmux (local terminal only)

tmux attach -t claude-code
tmux attach -t cursor-agent
`

$3

When the exit timeout is enabled and reached:
1. Server detects no user activity for the configured duration
2. Kills the tmux session
3. Notifies all connected clients with "Session Expired" message
4. Closes all WebSocket connections
5. Shuts down the server
6. Exits the process

Result: Full cleanup, similar to web exit. Web clients see a "Session Expired" overlay.

Note: Exit timeout is disabled by default. Enable with --exit-timeout or -E for security in shared environments.

Troubleshooting

$3

Install tmux (see Requirements section above).

$3

Make sure Claude Code CLI is installed and in your PATH:

`bash


Check if claude is available


which claude
`

$3

Install the Cursor Agent CLI:

`bash


Install

curl https://cursor.com/install -fsS | bash

Verify installation

which agent
`

$3

Make sure you're authenticated:

`bash


Interactive login (opens browser)

agent login

Check status

agent status

Or use API key

export CURSOR_API_KEY=your_api_key_here
`

$3

This can happen if node-pty's spawn-helper isn't executable. Fix with:

`bash
chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper
`

Or reinstall dependencies:

`bash
rm -rf node_modules && npm install
`

$3

Sign up at ngrok.com and authenticate:

`bash
ngrok config add-authtoken YOUR_TOKEN
`

$3

Free ngrok accounts are limited to 1 simultaneous tunnel. If you see this error, it means an ngrok process from a previous session is still running.

aigo will detect this and show you the command to kill it:

`
Error: An ngrok process is already running.
Free ngrok accounts only allow 1 simultaneous tunnel.

To kill the existing ngrok process, run:
kill 12345

Or to run without a tunnel:
aigo --tunnel none cursor
`

You can also find and kill ngrok manually:

`bash


Find ngrok processes

pgrep -f "ngrok http"

Kill by PID

kill

Or kill all ngrok processes

pkill -f "ngrok http"
`

$3

If cloudflared fails to connect:

`bash


Check if cloudflared is installed

which cloudflared

Test a quick tunnel manually

cloudflared tunnel --url http://localhost:3000

Check for firewall issues (verbose output)

cloudflared tunnel --url http://localhost:3000 --loglevel debug
`

$3

- Check that the server is running
- Ensure the URL includes the correct token
- If using a tunnel, make sure it's still active

$3

Try resizing your browser window to trigger a terminal resize.

Development

`bash


Clone the repository

git clone
cd aigo

Install dependencies

npm install

Run without installing globally

node bin/vigo.js claude
node bin/vigo.js cursor

Watch for changes (requires nodemon)

npx nodemon bin/vigo.js claude
`

$3

Bump the minor version and publish to npm:

`bash
make publish-minor # bump minor (e.g. 1.0.1 → 1.1.0), then publish
make publish-patch # bump patch (e.g. 1.0.1 → 1.0.2), then publish
`

Each runs npm version minor or npm version patch (updates package.json and creates a git commit/tag) then npm publish`.

License

MIT