A local UI for the Codex app — read your conversations, send messages, switch models, and monitor agent activity, all from a clean web interface running on your machine.
Built by @anshuchimala.
This is an independent project and is not affiliated with, endorsed by, or sponsored by OpenAI. I'm just an indie dev who likes to build with AI!
Farfield connects to the Codex desktop app over its local IPC socket and app-server API, then exposes a polished web UI at localhost:4312. You get:
- Thread browser — sidebar grouped by project with all your active Codex threads
- Chat view — read and send messages, switch collaboration mode, model, and reasoning effort
- Plan mode toggle — flip Codex into plan mode for any thread
- Agent monitoring — live stream events, pending user input requests, and interrupt controls
- Debug tab — full IPC history, payload inspection, and replay
- Node.js 20+
- pnpm 10+
- Codex desktop app installed and running locally
pnpm installpnpm devThat's it. Both the backend and frontend start in parallel.
- Backend:
http://127.0.0.1:4311 - Frontend:
http://127.0.0.1:4312— open this in your browser
The frontend proxies /api and /events to the backend automatically.
Farfield now supports a secure remote flow for iPhone access:
- Network access over your private Tailscale tailnet
- App PIN login (HTTP-only session cookie)
- Full control remotely (send, interrupt, and respond to input requests)
- Remote Debug endpoints disabled by default
tailscale upFARFIELD_AUTH_PIN=1234 pnpm dev:remoteFARFIELD_AUTH_PIN is required when binding HOST=0.0.0.0.
Optional env vars:
FARFIELD_SESSION_TTL_SECONDS(default:604800, 7 days)FARFIELD_REMOTE_DEBUG_ENABLED(default:0)FARFIELD_AUTH_COOKIE_NAME(default:farfield_session)
tailscale ip -4Open http://<tailscale-ip>:4312 in Safari on your iPhone (with Tailscale connected to the same tailnet), then enter your PIN.
- Install and sign in to Tailscale on iPhone.
- Connect Tailscale on iPhone and Mac.
- Open
http://<tailscale-ip>:4312in Safari. - Enter your Farfield PIN on the lock screen.
- Local loopback requests: Debug is always available.
- Remote requests: Debug is blocked unless
FARFIELD_REMOTE_DEBUG_ENABLED=1.
| Symptom | Cause | Fix |
|---|---|---|
AUTH_REQUIRED / lock screen loops |
Missing or expired session | Enter PIN again via the lock screen. |
FARFIELD_AUTH_PIN is required when HOST is not loopback |
dev:remote started without PIN |
Start with FARFIELD_AUTH_PIN=... pnpm dev:remote. |
| No Tailscale URLs shown | Tailscale is not installed/running | Install Tailscale and run tailscale up. |
| iPhone cannot connect | Wrong address or not on same tailnet | Verify tailscale ip -4, then open http://<ip>:4312. |
| Debug tab unavailable remotely | Remote debug is intentionally disabled | Set FARFIELD_REMOTE_DEBUG_ENABLED=1 only when needed. |
pnpm build # Build all packages
pnpm test # Run all tests
pnpm typecheck # TypeScript type checking across all packages
pnpm lint # Lint all packagesRun a single app:
pnpm --filter @farfield/server dev
pnpm --filter @farfield/web devapps/
server/ HTTP + SSE backend (TypeScript)
web/ React frontend (Vite + Tailwind)
packages/
protocol/ Zod schemas and inferred types for all wire formats
api/ Typed clients for the Codex app-server and desktop IPC
scripts/
sanitize-traces.mjs Redact trace files for safe fixture use
packages/protocolis the single source of truth for all data shapes. Everything is Zod — no silent coercion, no shape drift, hard failures on unknown payloads.packages/apiwraps the Codex IPC socket and app-server HTTP API with typed clients and a high-level service layer.apps/serverserves the REST and SSE endpoints the UI depends on, and manages the IPC connection lifecycle.apps/webis a Vite + React + Tailwind app. No heavy framework.
The Debug tab lets you record IPC traffic as trace files. Raw traces go in traces/ (git-ignored). To generate sanitized test fixtures:
pnpm sanitize:tracesSanitized files land in packages/protocol/test/fixtures/sanitized/.
MIT