The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* A page a program in a harness's pane opens — Claude Code's `/login`, `gh auth login` — opened where the person
* is. Every engine pane's `BROWSER` is this daemon's shim (lib/browserShim.ts), which asks here first
* (`browser_open`, from a tool client on this computer). The page goes to the phone that last typed into that
* pane; otherwise the shim opens this computer's browser, as the program would have.
*
* A sign-in that returns to the program at `http://localhost:PORT/callback` would land on the phone's own
* localhost. The phone listens there itself, catches the redirect and sends it back (`browser_callback`), and it
* is replayed here, to the program still waiting on that port. Only to a port and path a page sent to that very
* phone named, once, while it is fresh: a wrong redirect is not harmless (Claude Code drops the whole sign-in on
* a mismatched `state`), and a phone must not reach arbitrary ports of this computer.
*/
/** Who typed into an agent's terminal last, as the terminal stream knows them. */
export interface InputSource {
connId: string
/** What the client said it is on `terminal_open` (`phone`, `desktop`, `web`…); null when it said nothing. */
kind: string | null
}
export interface BrowserDeps {
/** The harness whose pane this is (`$TMUX_PANE` of the program opening the page). */
agentOfPane: (pane: string) => string | undefined
/** A frame for one client, sealed to it when it is remote; false when it cannot be sent. */
sendTo: (connId: string, type: string, payload: Record<string, unknown>) => boolean
isLocal: (connId: string) => boolean
/** Who is on a connection, the same across its reconnects (a paired phone's key). The phone's line drops
* while the browser covers the app, and it sends the redirect back over a new connection. */
who: (connId: string) => string
/** GET [url] on this computer; resolves with the HTTP status. */
replay: (url: string) => Promise<number>
now: () => number
/** One line about what happened, for the daemon's log. Never the page or the redirect: they carry codes. */
log: (line: string) => void
}
/** How long a phone has to sign in and send the redirect back. */
export const CALLBACK_FOR_MS = 10 * 60_000
interface Pending { who: string, port: string, path: string, until: number }
const LOOPBACK = new Set(['localhost', '127.0.0.1'])
/** The `http://localhost:PORT/...` a page will redirect to, when it is that kind of sign-in. */
function loopbackRedirect(page: URL): URL | null {
try {
const redirect = new URL(page.searchParams.get('redirect_uri') ?? '')
return redirect.protocol === 'http:' && LOOPBACK.has(redirect.hostname) && redirect.port ? redirect : null
} catch {
return null
}
}
export function createBrowser(deps: BrowserDeps) {
const lastInput = new Map<string, InputSource>()
const pending: Pending[] = []
/** The terminal stream's `onInput`: keystrokes a person typed, and from where. */
const typed = (agentId: string, source: InputSource): void => { lastInput.set(agentId, source) }
/** `browser_open` {pane, url}: whether a phone took the page. False tells the shim to open it here. */
const open = (payload: Record<string, unknown>): Record<string, unknown> => {
const agentId = typeof payload.pane === 'string' ? deps.agentOfPane(payload.pane) : undefined
const source = agentId ? lastInput.get(agentId) : undefined
let page: URL
try { page = new URL(String(payload.url ?? '')) } catch { return { handled: false } }
if (!agentId || !source || source.kind !== 'phone' || deps.isLocal(source.connId)) return { handled: false }
if (page.protocol !== 'https:' && page.protocol !== 'http:') return { handled: false }
if (!deps.sendTo(source.connId, 'browser_open', { agentId, url: page.href })) {
deps.log(`[browser] ${agentId} page not sent to the phone; opening it here`)
return { handled: false }
}
const redirect = loopbackRedirect(page)
if (redirect) pending.push({ who: deps.who(source.connId), port: redirect.port, path: redirect.pathname, until: deps.now() + CALLBACK_FOR_MS })
deps.log(`[browser] ${agentId} page sent to the phone${redirect ? `, waiting for its sign-in on port ${redirect.port}` : ''}`)
return { handled: true }
}
/** `browser_callback` {url} from [connId]: the redirect the phone caught, replayed to the waiting program. */
const callback = async (payload: Record<string, unknown>, connId: string): Promise<Record<string, unknown>> => {
let caught: URL
try { caught = new URL(String(payload.url ?? '')) } catch { return { error: 'BAD_URL' } }
const now = deps.now()
for (let i = pending.length - 1; i >= 0; i--) if (pending[i]!.until < now) pending.splice(i, 1)
const who = deps.who(connId)
const at = pending.findIndex((entry) => entry.who === who && entry.port === caught.port && entry.path === caught.pathname)
if (caught.protocol !== 'http:' || !LOOPBACK.has(caught.hostname) || at === -1) {
deps.log(`[browser] a sign-in on port ${caught.port || '?'} was refused: no page sent to that phone waits there`)
return { error: 'NOT_EXPECTED' }
}
pending.splice(at, 1)
try {
const status = await deps.replay(`http://127.0.0.1:${caught.port}${caught.pathname}${caught.search}`)
deps.log(`[browser] sign-in handed to the program on port ${caught.port}: HTTP ${status}`)
return { ok: status < 400, status }
} catch (error) {
deps.log(`[browser] sign-in not handed to the program on port ${caught.port}: ${error instanceof Error ? error.message : String(error)}`)
return { error: 'NOT_DELIVERED' }
}
}
return { typed, open, callback }
}
export type Browser = ReturnType<typeof createBrowser>