# ADR 006: t3-code as the agent orchestrator - HTML version: https://robbiepalmer.me/projects/homelab/adrs/006-t3-code - Project: Home Lab (https://robbiepalmer.me/projects/homelab.md) - Status: Accepted - Date: 2026-08-02 # Context The Mac mini's primary use case is remote, mobile-friendly, agentic development. It hosts four coding harnesses, [Claude Code](/projects/homelab/adrs/002-claude-code), [Codex](/projects/homelab/adrs/003-codex) (two subscriptions), [Grok Build](/projects/homelab/adrs/004-grok-build), and [OpenCode](/projects/homelab/adrs/005-opencode), and I want to drive them from a phone over the tailnet without juggling four different CLIs or web UIs. The harnesses themselves are already covered by earlier decisions. Claude Code [inherited](/projects/homelab/adrs/002-claude-code) from `personal-knowledge-graph:012-claude-code`, Codex [inherited](/projects/homelab/adrs/003-codex) from `personal-knowledge-graph:043-codex`, plus [Grok Build](/projects/homelab/adrs/004-grok-build) and [OpenCode](/projects/homelab/adrs/005-opencode). This ADR is about the *orchestration layer* that runs them all from one surface, and specifically about hosting it on the always-on hub. Requirements: * **One surface, many harnesses.** A single GUI that can start threads through any of the four harnesses. Each harness offers its own model and tool choices, and each can run many threads. * **Thread triage.** The sidebar must show work in progress, threads waiting for attention, and old sessions I have not settled. * **Bring your own subscription.** It must not resell tokens or require its own API keys. It wires in the credentials and plans I already pay for (including both distinct Codex subscriptions, each keeping its own allowance). * **Mobile-friendly and remote.** It has to be usable from a phone over the tailnet. A headless server on the hub must back the web interface. * **Git-native workflow.** Agents write to their own branches; committing, pushing, and opening PRs should be one button. # Decision Use **t3-code** as the open-source GUI/orchestrator for the four coding harnesses and their agent threads, hosted on the Mac mini. t3-code runs as a Node.js server wrapping the agent backends (it starts `codex app-server` per session and can connect to the other harnesses), serves a web UI, and exposes a headless `t3 serve` mode bound to the tailnet IP. That headless mode is what makes the phone workflow work: `t3 serve --host "$(tailscale ip -4)"` lets me pair a phone or the desktop app to the hub's server, scan a QR code, and drive real agent sessions with the repos, credentials, and tools already prepared on the Mac mini. The sidebar keeps running threads, attention requests, and old sessions visible without opening each conversation. The same thread view handles diff review, commit, push, and PR creation. That workflow beats the provider interfaces I used even when I stay within one harness. Every added harness uses the same sidebar and thread workflow. Each of the two Codex subscriptions is its own account; t3-code manages them as separate providers so I can draw down each plan's allowance and pick the best-fitting one per task. # Alternatives ## Use each harness's own CLI/web UI, no orchestrator * **Pros**: No extra layer to maintain. * **Cons**: t3-code doesn't interfere with the agent harnesses. It drives the same CLIs directly, so the agents are just as capable either way; the difference is the surface. Without an orchestrator there are four different UIs, four sets of shortcuts and mental models, and no shared thread or project context. I used the Claude and Codex apps from mobile for a while, and t3-code is a far better UX for juggling multiple sessions and coordinating work on GitHub. Codex required a user-provided machine to run on anyway before remote development environments existed. * **Decision**: Rejected. The orchestrator coordinates the work while the harnesses still run the agents. ## Write my own orchestrator / web shell * **Pros**: Full control, exactly my workflow. * **Cons**: Rebuilds what t3-code already does (session management, provider switching, diff viewing, PR workflow, remote pairing) for zero marginal benefit. * **Decision**: Rejected. t3-code is open source (MIT) and forkable. If it doesn't do something, I extend it rather than reimplement it. ## Only run hosted cloud agent environments * **Pros**: No host to keep alive. * **Cons**: Fresh environments re-bootstrap dependencies and context each time; I'd lose the prepped repos and credentials on the hub. Also doesn't help with the two Codex subscriptions I already pay for. * **Decision**: Rejected. The hub's existing environment is the value. # Consequences ### Pros * **One mobile surface for all agent work**, over the tailnet, from the sofa. * **Both Codex subscriptions managed as separate providers**, each keeping its own allowance. * **BYOK economics**: no extra token reseller; my existing subscriptions power everything. * **Git-native**: one-click commit, push, and PR per agent thread. * **Open source and forkable**: it's infrastructure I can own, like the rest of the lab. ### Cons * **New orchestration dependency**: t3-code is young; the provider landscape it wraps changes quickly. * **Host availability**: remote sessions depend on the Mac mini staying up, which makes home power and broadband a correlated single point of failure. [ADR 025](/projects/homelab/adrs/025-cloud-remote-development-plane) proposes an independent cloud instance without changing t3-code's role. * **Configuration surface**: agent auth, t3-code pairing, and the tailnet binding all need to be kept working together. --- Markdown index of this site: https://robbiepalmer.me/llms.txt