ai-or-die Documentation

Complete reference for the universal AI coding terminal. One command, every tool, right in your browser.

Getting Started

Install

Three ways to get running:

Option 1: npx (no install)

npx ai-or-die

Option 2: Global install

npm install -g ai-or-die
ai-or-die

Option 3: Standalone binary

Download a pre-built binary from the releases page. No Node.js required. Available for Linux x64 and Windows x64.

First run

When you run npx ai-or-die, the following happens:

1. The server starts on port 7777 (configurable with --port).
2. A secure authentication token is generated automatically.
3. Your default browser opens with the token embedded in the URL.
4. ai-or-die scans your system for installed CLI tools (Claude, Copilot, Gemini, Codex).
5. Available tools appear as clickable cards in the UI. Unavailable tools are shown as disabled.

Tool auto-detection

On startup, ai-or-die searches common installation paths for each supported CLI tool. It checks both standard system paths and tool-specific locations (for example, ~/.claude/local/claude for Claude Code). Tools that are found become available in the browser interface.

Folder mode

Click the folder icon in the toolbar to browse and select a working directory for your session. The file browser is sandboxed to the base directory and its subdirectories. You can also create new folders directly from the UI.

CLI Reference

Full list of command-line flags:

Usage examples

# Start on a custom port
ai-or-die --port 8080

# Use a specific auth token
ai-or-die --auth my-secret-token

# Headless mode (no browser auto-open)
ai-or-die --no-open --port 3000

# HTTPS with certificates
ai-or-die --https --cert cert.pem --key key.pem

# Remote access via Dev Tunnels
ai-or-die --tunnel

# Development mode with verbose output
ai-or-die --dev

# Custom tool names in the UI
ai-or-die --claude-alias "Claude 4" --copilot-alias "GH Copilot"

# Set subscription plan for usage tracking
ai-or-die --plan pro

Architecture

High-level overview

Entry point

bin/ai-or-die.js uses Commander.js for CLI parsing. It reads flags, resolves configuration, and hands off to the server module.

Server

src/server.js runs an Express application with WebSocket support. It handles session management, authentication middleware, rate limiting (100 requests per minute per IP), static file serving for the client, and all REST API endpoints.

Bridge layer

Each CLI tool has its own bridge class (src/*-bridge.js) extending BaseBridge. Every bridge implements a common interface:

• startSession(sessionId, options)
• sendInput(sessionId, data)
• resize(sessionId, cols, rows)
• stopSession(sessionId)

Bridges handle platform-aware command discovery, process spawning via node-pty, and graceful shutdown (SIGTERM followed by SIGKILL after 5 seconds).

Client

src/public/ contains the browser application: vanilla JavaScript with xterm.js for terminal emulation, tabbed session management, PWA support via a service worker, and the file browser UI.

Tunnel manager

src/tunnel-manager.js manages the Microsoft Dev Tunnel lifecycle. It handles login, tunnel creation, hosting, and cleanup.

Session store

File-based persistence at ~/.ai-or-die/sessions.json. Sessions auto-save every 30 seconds using atomic writes. Stale sessions older than 7 days are cleaned up automatically on startup.

Key design decisions

• Bridge-per-CLI architecture for extensibility. Adding a new tool means creating a new bridge class.
• Session-centric model with multi-device access. The same session can be viewed from different browsers.
• Output buffering keeps the last 1000 lines for reconnection replay.
• node-pty over child_process for full terminal emulation (colors, cursor movement, screen clearing).
• Authentication by default. Every server start generates a token unless explicitly disabled.
• Path validation and sandboxing. All file operations resolve symlinks and reject traversal attempts.

Supported Tools

Claude Code

Anthropic's AI coding assistant for code generation, editing, and reasoning.

• Install: https://claude.ai/code
• Auto-trust prompt handling: ai-or-die automatically accepts Claude's workspace trust prompt so sessions start without manual intervention.
• Dangerous flag: --dangerously-skip-permissions

GitHub Copilot

GitHub's AI pair programmer for suggestions and code completion.

• Install: https://github.com/features/copilot
• Dangerous flag: --yolo

Google Gemini

Google's multimodal AI assistant.

• Install: https://github.com/google-gemini/gemini-cli

OpenAI Codex

OpenAI's code generation agent.

• Install: https://openai.com/codex
• Dangerous flag: --dangerously-bypass-approvals-and-sandbox

Terminal

Raw shell access. Uses bash on Linux and PowerShell on Windows. Always available regardless of whether other tools are installed.

Features In Depth

Multi-session support

• Tabbed interface with drag-and-drop reordering.
• Each tab runs a different tool independently.
• Sessions persist across server restarts (the output buffer is saved to disk).
• MRU (most recently used) tracking for session switching.

Real-time terminal

• xterm.js with full 256-color ANSI support.
• WebSocket streaming with output coalescing at approximately 60fps (16ms intervals).
• Terminal search with Ctrl+F or the search icon in the toolbar.
• Theme switching with 10+ built-in themes.
• Customizable font size and font family (MesloLGS Nerd Font by default).

File browser

• Open with Ctrl+B or the toolbar button.
• Browse directories, preview files (images, text, JSON, CSV, PDF).
• Edit files with Ace Editor, including auto-save and conflict detection.
• Upload files via drag-and-drop, the file picker, or clipboard paste.
• Download files directly from the browser.
• Security: path validation, executable blocklist, and rate limiting on writes.

Usage analytics

• Track Claude token usage with burn rate predictions.
• Plan-specific limits: Pro (19K tokens), Max5 (88K), Max20 (220K).
• 5-hour rolling session windows.
• Visual indicators with confidence scoring.
• Real-time session timer.

Remote access (Dev Tunnels)

• Built-in Microsoft Dev Tunnels support.
• Run: ai-or-die --tunnel
• Auto-login and persistent named tunnels per machine.
• Auth is disabled when a tunnel is active (the tunnel controls access).
• Requires the devtunnel CLI to be installed.

VS Code tunnel integration

• Per-session VS Code tunnel support.
• Open your working directory in VS Code from the browser.
• Health monitoring with auto-restart.

Progressive Web App (PWA)

• Installable on any device.
• Offline-capable shell with service worker caching.
• Works on iOS Safari, Android Chrome, and desktop browsers.

Command palette

• Open with Ctrl+K.
• Quick access to sessions, tools, settings, and the file browser.
• Fuzzy search across all available commands.

Image handling

• Paste images directly into terminal sessions.
• Drag-and-drop image support.
• Preview modal with captions.
• Temp file management with auto-cleanup.

Split views

• Side-by-side terminal splits.
• Independent WebSocket connections per split.
• Resizable split containers.

Cross-platform

• Windows (ConPTY) and Linux support.
• CI-tested on both platforms.
• Standalone SEA binaries available (no Node.js required).

WebSocket API

Connection

# Standard
ws://localhost:7777?token={authToken}

# HTTPS
wss://localhost:7777?token={authToken}

# Auto-join an existing session
ws://localhost:7777?token={authToken}&sessionId={sessionId}

Client-to-server messages

create_session

Create a new session.

{
  "type": "create_session",
  "name": "My Claude Session",
  "workingDir": "/home/user/project"
}

join_session

Connect to an existing session. Receives the output buffer replay.

{
  "type": "join_session",
  "sessionId": "abc-123"
}

leave_session

Disconnect from a session without stopping the tool.

{
  "type": "leave_session",
  "sessionId": "abc-123"
}

start_claude / start_codex / start_copilot / start_gemini / start_terminal

Launch a CLI tool in the current session.

{
  "type": "start_claude",
  "sessionId": "abc-123",
  "cols": 120,
  "rows": 40,
  "dangerous": false
}

The dangerous field enables the tool's dangerous/yolo mode flag when set to true.

input

Send user input to the running tool.

{
  "type": "input",
  "sessionId": "abc-123",
  "data": "Hello, Claude!\r"
}

resize

Adjust terminal dimensions.

{
  "type": "resize",
  "sessionId": "abc-123",
  "cols": 160,
  "rows": 50
}

stop

Terminate the running tool in a session.

{
  "type": "stop",
  "sessionId": "abc-123"
}

ping

Keepalive message.

{
  "type": "ping"
}

get_usage

Request current token usage data.

{
  "type": "get_usage",
  "sessionId": "abc-123"
}

Server-to-client messages

connected

Sent immediately after WebSocket connection is established.

{
  "type": "connected",
  "sessions": [
    { "id": "abc-123", "name": "My Session", "toolRunning": "claude" }
  ]
}

session_created

{
  "type": "session_created",
  "sessionId": "abc-123",
  "name": "My Session"
}

session_joined

Includes the output buffer for replay.

{
  "type": "session_joined",
  "sessionId": "abc-123",
  "buffer": "... previous output ..."
}

session_left

{
  "type": "session_left",
  "sessionId": "abc-123"
}

claude_started / codex_started / copilot_started / gemini_started / terminal_started

{
  "type": "claude_started",
  "sessionId": "abc-123"
}

output

Terminal output from the running tool. Delivered as raw strings (may contain ANSI escape codes).

{
  "type": "output",
  "sessionId": "abc-123",
  "data": "\u001b[32mHello from Claude\u001b[0m\r\n"
}

exit

The tool process has exited.

{
  "type": "exit",
  "sessionId": "abc-123",
  "code": 0
}

error

{
  "type": "error",
  "message": "Session not found"
}

claude_stopped / codex_stopped / copilot_stopped / gemini_stopped / terminal_stopped

{
  "type": "claude_stopped",
  "sessionId": "abc-123"
}

usage_update

{
  "type": "usage_update",
  "sessionId": "abc-123",
  "usage": {
    "tokensUsed": 12500,
    "tokenLimit": 220000,
    "burnRate": 450,
    "confidence": 0.85
  }
}

session_deleted

{
  "type": "session_deleted",
  "sessionId": "abc-123"
}

pong

{
  "type": "pong"
}

info

Informational messages from the server (for example, tunnel URL, startup status).

{
  "type": "info",
  "message": "Dev tunnel ready at https://abc123.devtunnels.ms"
}

Session lifecycle

1. Client connects via WebSocket. Server sends connected with the list of existing sessions.
2. Client sends create_session. Server responds with session_created.
3. Client sends start_claude (or another tool). Server responds with claude_started.
4. Server streams output messages as the tool produces data.
5. Client sends input messages for user keystrokes.
6. When the tool exits, server sends exit followed by claude_stopped.
7. Client can leave_session and later join_session to reconnect with buffer replay.

REST API

All endpoints require authentication unless noted. Pass the token as a header (Authorization: Bearer <token>) or query parameter (?token=<token>).

Example requests

Check server health

curl http://localhost:7777/api/health \
  -H "Authorization: Bearer YOUR_TOKEN"

List sessions

curl http://localhost:7777/api/sessions/list \
  -H "Authorization: Bearer YOUR_TOKEN"

Create a session

curl -X POST http://localhost:7777/api/sessions/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Session", "workingDir": "/home/user/project"}'

Save a file (with conflict detection)

curl -X PUT http://localhost:7777/api/files/content \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/project/index.js", "content": "...", "hash": "abc123"}'

Security

Authentication

A unique token is auto-generated on every server start and embedded in the browser URL. You can set your own with --auth <token> or disable it entirely with --disable-auth. The token is accepted as a Bearer token in the Authorization header or as a ?token= query parameter.

Rate limiting

100 requests per minute per IP address by default. File write operations are limited to 30 per minute.

Path validation

All file paths are validated with symlink resolution. Directory traversal attempts (using .. or absolute paths outside the sandbox) are rejected with a 403 response.

HTTPS support

Enable TLS with the --https flag along with --cert and --key pointing to your SSL certificate and private key files.

File upload safety

• Executable extension blocklist: .exe, .bat, .cmd, .com, .msi, .scr, .ps1, and others.
• 10MB maximum file size.
• 30 write operations per minute rate limit.

Content security

All file content responses include X-Content-Type-Options: nosniff, Cache-Control: no-store, and sandbox headers to prevent execution of served content.

No data leaks

Everything runs locally on your machine. There is no telemetry, no external API calls, and no data collection. Your code never leaves your machine unless you explicitly enable --tunnel for remote access.

Configuration

Session persistence

Sessions are saved to ~/.ai-or-die/sessions.json every 30 seconds. This file stores session metadata, working directories, tool state, and the output buffer for each session.

Plan configuration

Set the subscription plan with the --plan flag or the CLAUDE_PLAN environment variable. This controls token usage tracking limits.

A custom plan mode uses P90-based detection to infer limits from observed usage patterns.

Tool aliases

Rename tools in the UI with alias flags or environment variables:

# Via flags
ai-or-die --claude-alias "Claude 4" --codex-alias "GPT Codex"

# Via environment variables
export CLAUDE_ALIAS="Claude 4"
export CODEX_ALIAS="GPT Codex"
ai-or-die

Themes

10+ built-in terminal themes, switchable from the UI settings panel or the command palette (Ctrl+K). Theme preference is persisted in the browser's local storage.

Fonts

The default terminal font is MesloLGS Nerd Font. Font size and family are configurable through the settings panel. Changes apply immediately to all open terminals.

Contributing

Quick setup

git clone https://github.com/animeshkundu/ai-or-die.git
cd ai-or-die
npm install
npm run dev

Testing

• Unit tests: npm test (Mocha with Node's built-in assert module)
• Browser tests: npm run test:browser (Playwright)
• Validation: bash scripts/validate.sh (Linux/macOS) or powershell scripts/validate.ps1 (Windows)

Code style

• Node.js with CommonJS modules
• 2 spaces for indentation
• Single quotes for strings
• Semicolons required
• kebab-case for file names, PascalCase for classes, camelCase for functions and variables
• Tests in test/*.test.js

Adding a new tool

1. Create a bridge class in src/ extending BaseBridge (see existing bridges as examples).
2. Implement startSession, sendInput, resize, and stopSession.
3. Register the bridge in src/server.js.
4. Add a WebSocket handler for start_<toolname>.
5. Add the tool to the client UI in src/public/app.js.

PR guidelines

• Tests are required for all changes.
• Update docs/specs/ when code behavior changes.
• Follow Conventional Commits: feat:, fix:, docs:, test:, chore:, refactor:.

Build standalone binary

npm run build:sea

This produces a Node.js Single Executable Application (SEA) binary that includes all dependencies. The output binary can be distributed without requiring Node.js on the target machine.