The Architecture Behind Tactic Remote: Building a Distributed Coding Platform

Building a remote development platform sounds straightforward on paper: run code on one machine, display it on another. In practice, the engineering challenges run deep. Every millisecond of latency erodes trust. Every dropped connection risks losing work. Every security shortcut invites catastrophe.

This article walks through the architecture of Tactic Remote — the decisions we made, the trade-offs we accepted, and the principles that guide our technical direction.

The Core Problem

Developers increasingly rely on AI-assisted coding tools like Claude Code, but these tools are bound to desktop terminals. You cannot step away from your desk without losing visibility into what your AI assistant is doing. Tactic Remote exists to solve this: your Mac remains the execution engine, while your iPhone becomes a first-class control surface.

The challenge is making this feel seamless rather than like a clunky remote desktop session.

Layered Architecture

Tactic Remote is built in four distinct layers, each with a clear responsibility boundary:

Layer 1: The Execution Engine (Mac)

At the foundation sits your Mac running Claude Code inside a tmux session. We chose tmux deliberately — it provides process persistence, session multiplexing, and a well-understood interface for programmatic terminal control. The Mac companion app manages tmux lifecycle, monitors session health, and exposes a lightweight HTTP API for upstream consumers.

Key design decisions at this layer:

• Process isolation: Each Claude Code session runs in its own tmux window, preventing cross-contamination between projects.
• State persistence: tmux sessions survive app restarts, network drops, and even system sleep cycles.
• Minimal footprint: The companion app adds negligible CPU and memory overhead when idle.

Layer 2: The Transport Layer

Between your Mac and iPhone sits the transport — either a direct local network connection or a Cloudflare Tunnel for remote access.

Local mode uses mDNS/Bonjour for device discovery and direct HTTP for data transfer. This gives sub-10ms round-trip times on a good network, making terminal streaming feel instantaneous.

Cloudflare Tunnel mode routes traffic through Cloudflare's edge network. This adds latency (typically 30-80ms) but enables access from anywhere — a coffee shop, a commuter train, or across the globe. We leverage Cloudflare's cloudflared daemon on the Mac side, which establishes an outbound-only connection, meaning no ports need to be opened on your firewall.

┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
│   iPhone    │◄───────►│  Transport Layer  │◄───────►│     Mac     │
│  (Control)  │   HTTP  │  Local / CF Edge  │   HTTP  │ (Execution) │
└─────────────┘         └──────────────────┘         └─────────────┘

Layer 3: The Session Manager

The session manager is the brains of the operation. Running on the Mac, it maintains a registry of active tmux sessions, tracks their state (idle, running, awaiting input), and handles the complex choreography of reconnection.

When your iPhone reconnects after a network interruption, the session manager must answer several questions in milliseconds:

1. Which sessions were active before the disconnect?
2. Has terminal output accumulated during the gap?
3. Are any sessions awaiting user approval for sensitive operations?
4. What is the current process state of each Claude Code instance?

We solve this through a combination of event sourcing (recording state transitions as immutable events) and snapshot caching (periodically capturing terminal buffer state for fast restoration).

Layer 4: The Mobile Interface

The iPhone app is intentionally not a terminal emulator. We made an early decision that cramming a full terminal onto a phone screen would create a terrible user experience. Instead, the mobile layer provides:

• Conversation view: See Claude's reasoning and outputs in a readable format.
• Terminal peek: Quick-glance access to raw terminal output when needed.
• Approval controls: One-tap approve/reject for operations requiring human confirmation.
• Notification bridge: Push notifications for task completions and approval requests.

Resilience Patterns

Real-world networks are unreliable. Phones lose signal in elevators. Wi-Fi drops when you walk between rooms. Our resilience strategy is built on three principles:

Assume disconnection is normal. Every component is designed to function independently during a network partition. The Mac continues executing. The iPhone caches the last known state. Reconnection triggers a state reconciliation protocol, not a full restart.

Minimize risk of lost work. Terminal output is buffered on the Mac side with configurable retention. Even if your iPhone is offline for an hour, reconnection is designed to restore what happened during that gap.

Fail visibly. When something goes wrong, the user sees an honest error message rather than an indefinite spinner. We invested heavily in connection state indicators that reflect reality within seconds.

Security by Design

Running AI-generated code remotely raises serious security questions. Our security model is covered in depth in our Security Model documentation, but the architectural highlights include:

• Zero-trust transport: All communication is encrypted, whether local (TLS) or tunneled (Cloudflare's encryption layer).
• Approval gates: Sensitive operations (file writes, shell commands, network access) require explicit mobile approval before execution.
• No Tactic Remote-managed cloud data plane: Tactic Remote does not upload source code to its own cloud services. Core sync is Mac-to-iPhone control traffic.

What's Next

Architecture is an ongoing process. We are actively working on multi-Mac support (connecting one iPhone to multiple development machines), collaborative sessions (multiple team members monitoring the same Claude Code run), and deeper IDE integrations. Each of these requires extending the architecture without compromising the reliability we have built.

If you're building distributed developer tools, we hope this overview is useful. And if you want to experience this architecture firsthand, get started here.