termly-cli CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Termly CLI is a universal NPM utility that enables remote terminal access to AI coding assistants (Claude Code, Aider, GitHub Copilot, Gemini, Grok, Cody, and 10+ more) from mobile devices. It works by:

1. Spawning AI tools in a PTY (pseudo-terminal) on the developer's computer
2. Streaming terminal I/O through WebSocket to a server with end-to-end encryption
3. Supporting session resume with circular buffering and sequence numbers
4. Managing multiple independent sessions simultaneously

Key constraint: Each CLI session supports exactly ONE mobile device connection.

Multi-Environment Architecture

The CLI supports three environments with hardcoded server URLs:

• Production (@termly-dev/cli): termly command → wss://api.termly.dev
• Development (@termly-dev/cli-dev): termly-dev command → wss://dev-api.termly.dev
• Local: TERMLY_ENV=local → ws://localhost:3000

Environments are detected by:

1. TERMLY_ENV=local environment variable (highest priority)
2. Binary name (cli-dev.js = dev, cli.js = production)
3. Default to production

Critical: Users CANNOT change server URLs. They are immutable per environment.

Development Commands

# Install dependencies
npm install

# Test production package
node bin/cli.js [command]
node bin/cli.js config  # Should show "Production" environment

# Test development package
node bin/cli-dev.js [command]
node bin/cli-dev.js config  # Should show "Development" environment

# Test local environment
TERMLY_ENV=local node bin/cli.js config  # Should show "Local Development"

# Link for global testing
npm link  # Creates 'termly' command

# Debug mode (enables verbose logging)
DEBUG=1 node bin/cli.js start --debug
node bin/cli.js start --debug

# View logs
tail -f ~/.termly/logs/cli.log

# Clean up test sessions
rm -rf ~/.termly

Publishing