T3 Code

The diagnostics page provides a comprehensive view of system and application health, including:

• Aggregated Metrics: CPU, memory, I/O, and process counts.
• Overhead Tracking: Breakdown of overhead from the backend, Electron, and the monitor itself.
• System State: Power and thermal state information.
• Collector Health: Status of collectors and information regarding restarts.
• Historical Data: CPU and I/O history graphs.
• Process Management: A collapsible live process tree and safe process signaling for backend descendants.
• Application I/O: Instrumented logical application I/O metrics.

T3 Connect Relay is the hosted control plane for T3 Connect. It is responsible for the orchestration and management of connections between clients and remote environments, but it is not in the hot path for regular T3 Code traffic. Once a client connects, API and WebSocket traffic flows directly between the client and the environment.

Core Responsibilities:

• Linking T3 Code environments to a cloud account.
• Provisioning and tracking managed environment endpoints.
• Issuing short-lived credentials for client-to-environment connections.
• Listing linked environments and registered mobile devices.
• Managing mobile notification preferences and APNs tokens.
• Delivering mobile notifications and Live Activity updates based on agent activity.
• Persisting relay state and providing diagnostic traces.

To ensure exact diffs and the ability to revert changes, every 'turn' in a session is bracketed by workspace checkpoints.

• Storage: Checkpoints are captured as hidden Git references using the VcsCheckpointOps contract (implemented via Git in the VCS driver).
• Coordination: The CheckpointReactor manages the lifecycle of these checkpoints, including baseline capture, completed-turn capture, diff projection, and reverting both the workspace and the provider conversation.
• Querying: CheckpointDiffQuery is used to retrieve diffs for specific turns or entire threads.

Permission modes are mapped to specific approval and sandbox settings by the underlying provider. While the high-level labels remain consistent, the implementation varies:

• Codex: Translates modes into specific approval policies and sandbox levels. For example, Supervised enables CLI prompting and a restricted workspace, while Full access disables both.
• Claude: Uses its own internal auto permission mode for the Auto setting.
• OpenCode: Lacks an equivalent for the Auto mode and falls back to Supervised behavior.
• Mobile: Supports all four modes, but labels the Supervised mode as Approve actions.

T3 Code uses a one-time token exchange to establish secure, session-based access without requiring long-lived secrets upfront.

The Pairing Lifecycle

1. Token Issuance: The server (t3 serve) issues a one-time owner pairing token.
2. Exchange: The remote device (client) exchanges this token with the server.
3. Session Creation: The server creates an authenticated session for that specific device.

Note: After the initial pairing, access is session-based. You do not need to reuse the original token unless you are pairing a new device.

An AdvertisedEndpoint is a candidate endpoint provided by a server or desktop, containing a URL pair, reachability hints (loopback, LAN, private, public, tunnel), and compatibility markers.

Clients use these as hints. When selecting an endpoint (via selectPairingEndpoint), the client follows this priority order:

1. The saved defaultEndpointKey override.
2. The first endpoint marked isDefault.
3. The first endpoint whose reachability is not loopback.
4. The first endpoint compatible with the hosted HTTPS app.
5. If none match, no endpoint is selected (there is no unconditional loopback fallback).

Remote-capable environments in T3 Code are designed for untrusted networks using explicit authentication and secure tunnel exposure.

Key security principles include:

• No Obscurity: Tunnel exposure does not rely on hidden paths; it relies on explicit authentication.
• Secure Reconnection: Saved endpoints include sufficient authentication metadata to allow safe reconnections.
• Short-lived WebSocket Tickets: WebSocket authentication uses a dedicated short-lived ticket rather than passing long-lived tokens in query strings. This prevents token leakage in logs or browser history.
• Hosted Pairing Safety: Hosted pairing is a client-side convenience. Hosted apps must not receive pairing tokens via query parameters, must not store pairing state on the server, and must not assume an HTTP backend is reachable from an HTTPS browser context.

T3 Code organizes work into Projects and Threads using a filesystem-based approach.

• Project: The top-level workspace record. It contains a workspaceRoot and a title but does not contain threads directly; threads are separate entities in the orchestration model.
• Workspace root: The absolute filesystem path for a project, serving as the base directory for branches and worktrees.
• Worktree: An isolated Git worktree used for a specific thread. If a thread specifies a worktreePath, all operations for that thread occur within that isolated directory rather than the main working tree.

In T3 Code, terminal sessions are server-owned PTYs (Pseudo-Terminals). The server maintains the session and sends a raw byte stream to the clients. Clients receive this stream and send input and resize events back to the server.

Crucially, the choice of renderer is local to the client; renderer-specific data never crosses the network wire. This allows different platforms (Android, Web, etc.) to use different rendering engines while interacting with the same server-side session.

The Client Runtime is designed with a specific dependency direction to maintain separation between platform services and application logic:

1. Platform Services: Platform applications provide the platform services.
2. Connection Supervision: The connection module composes platform capabilities with authorization, relay, and rpc to supervise environment sessions.
3. State Management: Independent state modules consume the connection registry and expose focused state or Atom constructors to application-owned runtimes.

Important Note on Imports: Do not attempt to import from the package root. Use specific domain paths for state (e.g., state/shell) rather than a broad state export. Only subpath indices and explicitly exported domain files are considered public API boundaries.