Technical Guide: Collaborative AI Coding with mpai

Practical Summary of mpai

mpai is a terminal-native coordination layer designed to transform isolated AI coding sessions into shared team surfaces. It allows multiple users to participate in the same Codex or Claude Code conversation directly from their own terminals without requiring screen sharing, transcript pasting, or re-explaining context. By leveraging Tailscale for private networking, mpai enables a teammate to join an existing session while maintaining their own identity and authorship for every prompt sent. This tool is specifically built for developers who need to collaborate on complex AI-driven tasks while staying within their preferred terminal environments.

Prerequisites and System Requirements

To utilize mpai effectively, both the host and the guest must meet specific technical requirements. The host machine must be running macOS and have an active Tailscale network. The host must also have Node.js 20 or higher installed. The guest, or teammate, also requires Node.js 20 or higher to run the session without needing a global installation. The tool is currently in an alpha state, meaning it is designed for specific workflows involving Codex and Claude Code. Users should ensure they are operating within a non-sensitive pilot environment as the tool is not yet certified for large-scale enterprise deployments.

Initial Setup and Session Initiation

The setup process is designed to be straightforward for both parties. The host initiates the process by installing the tool and starting a session, which generates a private command for the teammate. The following command is used to begin the process on the host machine:

brew install godfaddaai/tap/mpai && mpai start

Once the host executes this, the tool verifies the machine, prompts for the names of the participants, and allows the host to select an existing session to share. The host then provides the generated private npx command to the teammate, who pastes it into their own terminal to join the session immediately.

Documented Collaborative Workflow

Once connected, the workflow allows for seamless interaction within the shared context. The teammate sees the shared session separately in their terminal and can follow the real-time transcript as new turns are persisted. When the teammate sends a prompt, it is attributed to them, ensuring that the AI agent and all participants know exactly who asked for what. This attribution is maintained within the native transcript of the underlying agent, such as Codex or Claude Code. The host retains control over the session, and sharing is strictly explicit, meaning only sessions intentionally shared by the host are accessible to the guest.

Security and Owner-Controlled Access

Security is a core component of the mpai architecture. The tool functions as a coordination layer rather than a transcript cloud or a remote shell. Because it utilizes Tailscale, all communication occurs over a private device network. Access is governed by explicit sharing rules where invites are bound to the first Tailscale identity that uses them. The system enforces narrow authority, meaning guests cannot perform arbitrary shell execution, file deletion, or archival. Furthermore, the tool provides an append-only prompt audit trail and uses the local Keychain for credentials, ensuring that the host maintains full oversight of the collaborative environment.

Limitations of the Current Alpha

As an alpha-stage project, mpai has documented boundaries that users must acknowledge. The tool is currently limited to macOS environments and requires an existing Tailscale network. While it supports Codex and Claude Code, standalone Codex sessions are set to view-only by default. Claude support is specifically targeted at the local Claude Code CLI store. Features such as physical sleep/wake handling and three-person certification are currently in development. Users are encouraged to review the official documentation to understand the full scope of the alpha-stage gates and current functional limitations.

Choosing When to Use mpai

mpai is best suited for development teams that are already heavily invested in terminal-based AI coding tools like Codex or Claude Code and need to bridge the gap between individual sessions. It is ideal for pair programming scenarios where context is deep and re-explaining the state of a 40-turn conversation is inefficient. Because it is an alpha product, it should be used for non-sensitive pilot projects where the team can provide feedback on session stability. By keeping the work within the terminal and avoiding external transcript clouds, teams can maintain a high degree of control over their proprietary code and AI interactions.

Support and Community Engagement

The project is built in the open, and the developers encourage active participation to improve the tool. Users are invited to star the project on GitHub and report any issues encountered during shared sessions. By installing the tool on two Macs and testing the collaborative features, teams can help identify edge cases and contribute to the hardening of the software. For detailed information on the security model, privacy policies, and acceptable use, users should refer to the resources provided at https://godfaddaai.github.io/multiplayer-ai. The project is independent and not affiliated with Tailscale, OpenAI, or Anthropic.