The modern developer workflow has evolved into a fragmented landscape of terminal windows and remote server connections. A typical high-productivity setup often involves three or more machines running concurrent AI CLI sessions, where a developer must manually relay context from a Claude session on a MacBook to a Gemini instance on a Linux workstation. This manual hand-off creates a cognitive bottleneck, forcing the human operator to act as the primary data bridge between autonomous agents that are technically capable of communicating but remain isolated by the boundaries of their respective operating systems.

The Architecture of a Distributed AI Control Plane

To resolve this fragmentation, telepty introduces a dedicated control plane designed to integrate remote instruction and screen reading across disparate environments. The fundamental architectural premise of telepty is the strict separation of the control plane from the data plane. In this model, the data plane consists of the actual AI CLI sessions—such as those powered by Claude, Codex, or Gemini—where the heavy lifting of reasoning and task execution occurs. telepty does not attempt to replace these agents or rewrite their internal logic. Instead, it functions as a thin orchestration layer that addresses these sessions and ensures the reliable delivery of commands.

This system is built for cross-platform versatility, offering native support for macOS, Linux, and Windows. This allows for seamless cross-machine transmission, where a command issued on one operating system can trigger an action and return a result from a machine running an entirely different OS. As an open-source project under the MIT license, the codebase is transparent and available for community auditing and extension.

Developers can deploy the environment quickly using the npm package manager. The installation is handled via the following command:

npm i -g @dmsdc-ai/aigentry-telepty

Once installed, the tool enables a remote control environment that abstracts the physical location of the AI agent. To initialize the system, users run:

npm i -g @dmsdc-ai/aigentry-telepty && telepty daemon start

Moving Beyond Manual Multiplexing and Framework Constraints

The technical distinction of telepty becomes clear when compared to traditional remote management tools like tmux or SSH. While tmux provides terminal multiplexing and SSH allows for secure remote access, both remain fundamentally manual. The human user must still explicitly attach to a session, type a command, and visually verify the output. telepty shifts this paradigm by making the session itself a programmable resource. By providing nine built-in skills for Claude Code, Codex, and Gemini CLI, telepty allows the LLMs themselves to use the tool as a capability. An agent can execute a `telepty inject` command to relay instructions to another agent on a different machine or use screen-reading functions to monitor the state of a remote session without human intervention.

This approach also differs from comprehensive agent frameworks that often require developers to rewrite their existing workflows or migrate their sessions into a proprietary environment. telepty avoids this friction by acting as an infrastructure layer that sits on top of already running sessions. It does not demand a change in how the AI operates, only in how the AI is accessed.

Connectivity is handled by delegating complex network tasks to proven industry standards rather than implementing a custom protocol. To manage key exchange, NAT traversal, and encryption, telepty operates on top of Tailscale and the WireGuard VPN protocol. This design choice significantly reduces the attack surface by relying on a hardened network layer. In environments where Tailscale is not available, the system falls back to SSH tunneling using the following syntax:

telepty connect user@host

Security is further reinforced through strict binding policies. The system binds exclusively to localhost (127.0.0.1) and Tailnet-specific IP addresses, ensuring that the control plane is not exposed to the public internet. By avoiding a 0.0.0.0 bind, the tool remains invisible to external port scans. Starting with version 0.7.1, the system explicitly rejects requests originating from browsers that attempt to access the control API or WebSocket paths on localhost, further insulating the infrastructure from web-based attack vectors.

While the system is robust across Unix-like environments, the Windows version remains in beta. Currently, the `read-screen` functionality on Windows is limited to returning the end of the output stream rather than a full cell grid representation of the terminal. Despite this limitation, the core utility of the tool—controlling multiple machines without switching terminal focus—remains intact through the use of `inject` and `read-screen` commands.

This transition from manual session management to a programmable control plane transforms the AI agent from a standalone tool into a node within a larger, distributed compute fabric.