LinkShell

Product Introduction

1. Definition: LinkShell is a high-performance, cross-platform Terminal Bridge and Pseudo-Terminal (PTY) relay system designed specifically for developers using AI coding assistants. It consists of a Node.js-based CLI (Command Line Interface), a WebSocket gateway, and native mobile applications (iOS/Android) that allow users to remotely monitor, interact with, and control terminal sessions—including complex AI agents like Claude Code, GitHub Copilot, and OpenAI Codex—directly from a smartphone.

2. Core Value Proposition: LinkShell exists to decouple the developer from their physical workstation without sacrificing the integrity of the development environment. By bridging real-time PTY sessions over secure WebSockets, it provides a "declaration of independence from the desk." It addresses the primary need for "vibe coding" and mobile-first developer workflows, allowing heavy computational tasks (compiling, training, or AI reasoning) to remain on powerful desktop hardware while providing low-latency, full-fidelity control via mobile devices.

Main Features

1. Real-time PTY Bridging via WebSocket: LinkShell utilizes a specialized architecture to capture the local Pseudo-Terminal (PTY) driver output and stream it via the LinkShell Gateway. Unlike traditional remote desktop solutions that stream heavy video data, LinkShell preserves raw terminal semantics, including ANSI colors, cursor movements, and readline signals. This ensures a native terminal feel on mobile using xterm.js rendering, maintaining 100% compatibility with interactive CLI tools and AI agents.

2. AI-Native Dynamic Island & Live Status: For iOS users, LinkShell integrates with the Dynamic Island and Live Activities to provide real-time updates on AI agent progress. Developers can see if Claude is "thinking," "coding," or "awaiting confirmation" at a glance. The system supports "Quick Actions," enabling users to approve or deny AI-generated commands (like npm test or git commit) directly from the lock screen or Dynamic Island without opening the full app.

3. WebRTC Remote Desktop & Screen Sharing: By invoking the --screen flag, LinkShell activates a parallel WebRTC stream. This provides a 30fps real-time view of the desktop environment, essential for developers who need to see graphical outputs or IDE changes alongside their terminal. The system includes an automatic fallback to screenshot streaming for high-latency or low-bandwidth network conditions, ensuring continuous visibility.

4. Transparent Port Forwarding & Web Preview: LinkShell includes a built-in tunneling mechanism for web development. When a developer starts a local dev server (e.g., Vite, Next.js on port 3000), LinkShell can relay the HTTP traffic through the gateway. This allows the mobile app’s "Browser" tab to preview the live application with full CSS/JS execution and HMR (Hot Module Replacement) support, effectively enabling mobile UI testing of a local desktop environment.

5. Single Controller State Sync & Reliability: To prevent input races across multiple devices, LinkShell implements a "Single Controller" locking model. It features a 15-second heartbeat mechanism, exponential backoff for auto-reconnection, and a 1000-line scrollback buffer. This architecture ensures that if a mobile connection drops (e.g., switching from Wi-Fi to 5G), the session remains alive on the host and resumes instantly upon reconnection.

Problems Solved

1. Pain Point: Desktop Tethering during AI Sessions: Modern AI agents (like Claude Code) often take minutes to complete complex refactoring tasks. LinkShell solves the problem of developers being "trapped" at their desks waiting for AI prompts or build completions. Users can start a task, walk away, and handle approvals via their phone.

2. Target Audience:

• AI-First Software Engineers: Developers using terminal-based AI agents who need mobile oversight.
• Full-Stack Developers: Users requiring simultaneous terminal control and mobile web previewing.
• DevOps & SREs: Professionals who need to perform quick hotfixes or monitor build pipelines on the go without the friction of a full SSH setup.
• Vibe Coders: Developers who prefer a flexible, nomadic workflow while maintaining high-performance hardware backends.

3. Use Cases:

• The "Coffee Shop" Handover: Starting a long cargo build or npm install at the office and monitoring progress on the subway.
• Mobile Hotfixes: Spotting a production log error on the phone and typing a quick git pull && pm2 restart fix via the mobile terminal.
• Remote AI Supervision: Reviewing and approving Claude's code suggestions while away from the keyboard.

Unique Advantages

1. Differentiation from SSH and Traditional VNC: Traditional SSH is often difficult to pair quickly and lacks native "approval" UI for AI agents. VNC/RDP is bandwidth-heavy and lacks terminal-specific optimizations. LinkShell offers a "Zero Config" LAN setup and a QR-code-based pairing system that bridges the gap between raw terminal access and modern mobile UI/UX.

2. Key Innovation: Decentralized Bridge Architecture: LinkShell does not force data through a centralized third-party cloud. Users can run their own Gateway (via Docker or Node) or use the built-in LAN gateway. This architecture ensures maximum privacy and data sovereignty, as the "link" is established directly between the user's CLI and their mobile device.

Frequently Asked Questions (FAQ)

1. Does LinkShell require a public server or VPS to function? No. LinkShell includes a built-in gateway that works out-of-the-box on your Local Area Network (LAN). Your phone can connect directly to your computer’s IP address. A public server (VPS) is only necessary if you want to access your terminal across different networks (e.g., accessing your home computer via 5G).

2. Which AI coding agents are compatible with LinkShell? LinkShell is provider-agnostic. It officially supports Claude Code, OpenAI Codex, and Gemini terminal sessions. Because it functions as a PTY bridge, it can technically wrap any interactive shell process, including standard Zsh/Bash, custom Python scripts, or other CLI-based AI tools.

3. How secure is the connection between my phone and my computer? LinkShell is designed with security in mind. In LAN mode, data never leaves your network. In remote mode, you are encouraged to deploy your own gateway with Nginx and SSL (WSS). Pairing is secured via a 6-digit dynamic code and QR scanning, and the "Single Controller" model ensures only one device can send input commands at any given time.

4. Can I preview my web application on my phone using LinkShell? Yes. LinkShell’s Port Forwarding feature allows you to input a local port (like 3000 or 8080) into the mobile app. The gateway then tunnels the web traffic, allowing you to view and interact with your local development website on your mobile browser with support for Hot Module Replacement (HMR).