# 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 agents — [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 agents themselves are already covered by earlier decisions — Claude Code
[inherited](/projects/homelab/adrs/002-claude-code) from `personal-site:012-claude-code`,
Codex [inherited](/projects/homelab/adrs/003-codex) from `personal-site: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 agents.** A single GUI that can start a session on any
  of the four agents with a model/tool choice, preserving thread and project
  context across them.
* **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, which means a web surface backed by a headless server on the hub,
  not a terminal on my laptop.
* **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 my coding agents,
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 agents), 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.

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 agent'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 — and Codex required a user-provided machine
  to run on anyway before remote development environments existed.
* **Decision**: Rejected. The orchestrator is a coordinator, not a
  replacement for 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 is exactly what an always-on hub is for — but it does make the hub a
  single point of failure for all agent work.
* **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