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
CLI: every new terminal tile opens with its guide, in fewer words
0xken15b484c3c6832a
diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex cf8a76d9e..359b7b633 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -214,9 +214,6 @@ import {prepareLogFile, trimLogFile, LOG_CHECK_INTERVAL_MS,} from './lib/log.js'-/** Written once the first terminal on this machine has said how `harness remote` works (engineLaunch.ts). */-const TERMINAL_HINT_MARKER = join(env.ADAPTER_DATA_DIR, 'terminal-remote-hint-shown')-// Claude's Stop hook fires when the agent finishes, but the transcript can lag a moment behind// (docs: "the transcript file may lag behind the in-memory conversation"). Acting immediately races// that flush → an empty recap + a premature close. So the Stop hook is a DELAYED fallback: poll, and@@ -238,6 +235,10 @@ const COMPUTER_ID_FILE = env.ADAPTER_COMPUTER_ID_FILE// The machine's display name, mirrored from the backend (`machine_meta` on connect + web renames) by the// daemon so the separate `harness status` process can print it. Absent = unnamed machine.const MACHINE_NAME_FILE = join(env.ADAPTER_DATA_DIR, 'machine-name')+/** The name a new terminal tile greets with: the machine's display name the backend gave it, else the host's. */+function terminalHintMachineName(): string {+ try { return readFileSync(MACHINE_NAME_FILE, 'utf-8').trim() || hostname() } catch { return hostname() }+}// The dial's session, held at module scope for the same reason `backendRef` is: shutdown() is defined// before the wiring that creates it, and the port has to be released on the way out.@@ -339,7 +340,7 @@ Machine:harness logs export zip the last 7 days of logs (app, CLI, dial, daemon) to the Desktopharness machines list the machines on this account (this computer's is marked)harness machines delete <id> remove ANOTHER machine (refuses this one; use \`harness logout\`)- harness remote from a Harness terminal tile: open a terminal on another machine and switch to it+ harness remote from a Harness terminal tile: open a terminal on another of your machines and move this tile to itharness version print the installed version (v${VERSION})harness update [--force] update to the latest build now (it also self-updates in the background;neither touches a local install-cli.sh build without --force)@@ -3901,7 +3902,6 @@ async function runForeground(session: AuthSession): Promise<void> {const { env: launchEnv, extraArgs, clearEnv } = built.overridesconst argv = buildEngineLaunchArgv(entry.engine, {...opts,- terminalHintMarker: TERMINAL_HINT_MARKER,bypassPermission: entry.bypassPermission === true,...(entry.permissionMode ? { permissionMode: entry.permissionMode } : {}),installIfMissing: enginePathOverride(entry.engine) ? undefined : engineInstallRecipe(entry.engine),@@ -4258,7 +4258,7 @@ async function runForeground(session: AuthSession): Promise<void> {const extraArgs = [...(gridLaunch?.args ?? []), ...dshArgs, ...(agent ? namedAgentArgs(engine, agent) : [])]// The first prompt is a launch option only — never part of `extraArgs`, which the registry row// carries into a relaunch (engineLaunch.ts, `firstPrompt`).- const launchOptions = { bypassPermission, ...(permissionMode ? { permissionMode } : {}), extraArgs: extraArgs.length ? extraArgs : undefined, installIfMissing, clearEnv, cwd, harnessNode: dsh ? true : undefined, ...(prompt ? { firstPrompt: prompt } : {}), terminalHintMarker: TERMINAL_HINT_MARKER }+ const launchOptions = { bypassPermission, ...(permissionMode ? { permissionMode } : {}), extraArgs: extraArgs.length ? extraArgs : undefined, installIfMissing, clearEnv, cwd, harnessNode: dsh ? true : undefined, ...(prompt ? { firstPrompt: prompt } : {}), terminalHint: { machineName: terminalHintMachineName() } }const command = buildEngineCommandArgv(engine, launchOptions)const argv = buildEngineLaunchArgv(engine, launchOptions)// A tmux route is enough to stream its screen. Register it before looking for a process so bothdiff --git a/cli/src/lib/engineLaunch.spec.ts b/cli/src/lib/engineLaunch.spec.tsindex 5a9870e7f..88be34efe 100644--- a/cli/src/lib/engineLaunch.spec.ts+++ b/cli/src/lib/engineLaunch.spec.ts@@ -12,7 +12,7 @@ import {NAMED_AGENT_ARGS,NamedAgentUnsupportedError,PERMISSION_MODES,- TERMINAL_HINT_LINES,+ terminalHintLines,buildEngineCommandArgv,buildEngineLaunchArgv,commandAvailableInInteractiveShell,@@ -106,20 +106,20 @@ describe('buildEngineLaunchArgv', () => {it('is the login shell itself behind a non-interactive wrapper that only raises the limit and enters the folder', () => {expect(buildEngineLaunchArgv('terminal', { cwd: '/work/project' }, '/bin/zsh')).toEqual(['/bin/zsh', '-c',- `${RAISE_OPEN_FILES_SH}if ! cd -- "$1"; then printf '%s\\n' 'harness: the selected working directory is unavailable.' >&2; fi\nshift 2\nexec "$@"`,- 'harness-terminal', '/work/project', '', '/bin/zsh', '-l',+ `${RAISE_OPEN_FILES_SH}if ! cd -- "$1"; then printf '%s\\n' 'harness: the selected working directory is unavailable.' >&2; fi\nshift\nexec "$@"`,+ 'harness-terminal', '/work/project', '/bin/zsh', '-l',])})it('gives bash no login flag (its rc file is where Ubuntu keeps PATH edits), and no folder means no cd', () => {expect(buildEngineLaunchArgv('terminal', {}, '/bin/bash')).toEqual([- '/bin/bash', '-c', `${RAISE_OPEN_FILES_SH}shift 2\nexec "$@"`, 'harness-terminal', '', '', '/bin/bash',+ '/bin/bash', '-c', `${RAISE_OPEN_FILES_SH}shift\nexec "$@"`, 'harness-terminal', '', '/bin/bash',])})it('falls back to /bin/sh rather than to an engine command when no shell resolves', () => {expect(buildEngineLaunchArgv('terminal', {}, 'relative-shell')).toEqual([- '/bin/sh', '-c', `${RAISE_OPEN_FILES_SH}shift 2\nexec "$@"`, 'harness-terminal', '', '', '/bin/sh',+ '/bin/sh', '-c', `${RAISE_OPEN_FILES_SH}shift\nexec "$@"`, 'harness-terminal', '', '/bin/sh',])})@@ -137,30 +137,33 @@ describe('buildEngineLaunchArgv', () => {expect(() => execFileSync('/bin/sh', ['-n', '-c', script])).not.toThrow()// The wrapper's `exec "$@"` runs the shell handed in argv; `true` in its place proves the// wrapper reaches the exec even when the cd failed (the terminal still opens, at $HOME).- const out = execFileSync('/bin/sh', ['-c', script, 'harness-terminal', '/nowhere/at/all', '', '/bin/sh', '-c', 'echo reached'], { stdio: ['ignore', 'pipe', 'pipe'] })+ const out = execFileSync('/bin/sh', ['-c', script, 'harness-terminal', '/nowhere/at/all', '/bin/sh', '-c', 'echo reached'], { stdio: ['ignore', 'pipe', 'pipe'] })expect(out.toString()).toContain('reached')})- it('says how `harness remote` works before the first prompt on a machine, and never again', () => {- const dir = mkdtempSync(join(tmpdir(), 'terminal-hint-'))- const marker = join(dir, 'shown')- const argv = buildEngineLaunchArgv('terminal', { terminalHintMarker: marker }, '/bin/sh')- expect(argv.slice(4, 6)).toEqual(['', marker])+ it('greets every new tile with the guide — where it is, agents, `harness remote` — before its prompt', () => {+ const argv = buildEngineLaunchArgv('terminal', { terminalHint: { machineName: 'MacbookPro.local' } }, '/bin/sh')+ expect(argv.slice(3)).toEqual(['harness-terminal', '', '/bin/sh'])expect(() => execFileSync('/bin/sh', ['-n', '-c', argv[2]])).not.toThrow()- const run = (): string => execFileSync('/bin/sh', ['-c', argv[2], 'harness-terminal', '', marker, '/bin/sh', '-c', 'echo prompt'], { stdio: ['ignore', 'pipe', 'pipe'] }).toString()- const first = run()- for (const line of TERMINAL_HINT_LINES) expect(first).toContain(line)- expect(first.trim().endsWith('prompt')).toBe(true)- expect(existsSync(marker)).toBe(true)- const second = run()- expect(second).not.toContain('harness remote')- expect(second.trim()).toBe('prompt')- rmSync(dir, { recursive: true, force: true })+ const run = (): string => execFileSync('/bin/sh', ['-c', argv[2], 'harness-terminal', '', '/bin/sh', '-c', 'echo prompt'], { stdio: ['ignore', 'pipe', 'pipe'] }).toString()+ // Every time, not once per machine: a new tile is a new person at a new prompt.+ for (const out of [run(), run()]) {+ for (const line of terminalHintLines('MacbookPro.local')) expect(out).toContain(line)+ expect(out).toContain('Terminal on MacbookPro.local.')+ expect(out).toContain('harness remote')+ expect(out.trim().endsWith('prompt')).toBe(true)+ }+ })++ it('the guide names the machine, falls back to "this machine", and fits an 80-column pane unwrapped', () => {+ expect(terminalHintLines(' ')[0]).toBe('harness: Terminal on this machine.')+ for (const line of terminalHintLines('office-imac')) expect(line.length).toBeLessThanOrEqual(78)})- it('with no marker named (a test, an older caller) there is no hint', () => {+ it('with no guide asked for (restore, restart, a test) the pane says nothing before its prompt', () => {const script = buildEngineLaunchArgv('terminal', {}, '/bin/sh')[2]expect(script).not.toContain('harness remote')+ expect(script).not.toContain('Terminal on')})})diff --git a/cli/src/lib/engineLaunch.ts b/cli/src/lib/engineLaunch.tsindex d439cb9af..f00abadf1 100644--- a/cli/src/lib/engineLaunch.ts+++ b/cli/src/lib/engineLaunch.ts@@ -210,11 +210,11 @@ export interface LaunchCommandOptions {*/firstPrompt?: string/**- * Terminal only: a file whose absence means this machine has not yet been told about- * `harness remote`; the shell prints the hint before its prompt and writes the file. The daemon- * names one under its data dir; a test names none and gets no hint.+ * Terminal only: print the tile's guide before the first prompt — what this pane is, that an+ * agent typed here becomes the tile, and `harness remote`. Every NEW terminal tile gets it+ * (`agent_create`); a pane rebuilt by restore or restart is not a new tile and names nothing here.*/- terminalHintMarker?: string+ terminalHint?: { machineName: string }/*** Extra argv the caller has already composed, appended last.*@@ -486,18 +486,24 @@ export function engineFallbackPrelude(engine: AgentEngine, shellPath: string, tm* gives the person a prompt.*//**- * What the first terminal on a machine says before its prompt — once, ever: the marker file names- * the machine as told. Only a tile can act on it (`harness remote` swaps the tile it is typed in),- * and a tile is where every terminal the daemon opens lives.+ * What a new terminal tile says before its prompt, every time one is opened: where it is, that an+ * agent typed here becomes the tile (and the shell is back when it exits), and `harness remote` —+ * the one thing only a tile can act on, since it swaps the tile it is typed in. Three lines, each+ * under 78 columns — a pane is 80 wide when it prints them, before the app has sized it, and a+ * wrapped line stays wrapped in the scrollback — in the same `harness:` voice as every other line+ * a pane prints.*/-export const TERMINAL_HINT_LINES = [- 'harness: a terminal on this machine. To open one on another of your machines, type',- 'harness: harness remote',- 'harness: pick the machine, and this tile switches to it.',-] as const+export function terminalHintLines(machineName: string): string[] {+ const where = machineName.trim() || 'this machine'+ return [+ `harness: Terminal on ${where}.`,+ 'harness: Run an agent here (claude, codex, …) and this tile becomes it.',+ 'harness: Terminal on another of your machines: harness remote',+ ]+}export function buildTerminalLaunchArgv(- opts: Pick<LaunchCommandOptions, 'cwd' | 'terminalHintMarker'> = {},+ opts: Pick<LaunchCommandOptions, 'cwd' | 'terminalHint'> = {},shell: string | undefined = undefined,): string[] {const candidate = shell === undefined ? currentUserShell() : shell@@ -506,13 +512,10 @@ export function buildTerminalLaunchArgv(const cwdPrelude = opts.cwd? `if ! cd -- "$1"; then printf '%s\\n' 'harness: the selected working directory is unavailable.' >&2; fi\n`: ''- // `$2` is the marker: absent, the hint is printed and the marker written, so it is said once per- // machine. Written with `:>` rather than touch, so nothing outside the shell is needed; a folder- // that cannot be written just says it again next time.- const hintPrelude = opts.terminalHintMarker- ? `if [ -n "$2" ] && [ ! -e "$2" ]; then printf '%s\\n' ${TERMINAL_HINT_LINES.map(shellSingleQuote).join(' ')} ''; : > "$2" 2>/dev/null || true; fi\n`+ const hintPrelude = opts.terminalHint+ ? `printf '%s\\n' ${terminalHintLines(opts.terminalHint.machineName).map(shellSingleQuote).join(' ')} ''\n`: ''- return [path, '-c', RAISE_OPEN_FILES_SH + cwdPrelude + hintPrelude + 'shift 2\nexec "$@"', 'harness-terminal', opts.cwd ?? '', opts.terminalHintMarker ?? '', path, ...loginArgs]+ return [path, '-c', RAISE_OPEN_FILES_SH + cwdPrelude + hintPrelude + 'shift\nexec "$@"', 'harness-terminal', opts.cwd ?? '', path, ...loginArgs]}/**diff --git a/cli/src/remoteCommand.spec.ts b/cli/src/remoteCommand.spec.tsindex eb3cff546..1906a9b84 100644--- a/cli/src/remoteCommand.spec.ts+++ b/cli/src/remoteCommand.spec.ts@@ -104,7 +104,7 @@ describe('pickMachine', () => {await new Promise((resolve) => setTimeout(resolve, 5))io.press('up', 'enter') // onto machine-remote-1 (offline)await new Promise((resolve) => setTimeout(resolve, 5))- expect(io.written()).toContain('machine-remote-1 is offline — run `harness start` there, or choose one that is online.')+ expect(io.written()).toContain('machine-remote-1 is offline. Run `harness start` there, or choose an online machine.')io.press('down', 'enter')expect(await picked).toEqual(machines[2])})@@ -181,7 +181,7 @@ describe('remoteCommand', () => {for (const tmuxPane of [undefined, '', '%x']) {const d = deps({ tmuxPane })expect(await remoteCommand(d)).toBe(1)- expect(d.errors[0]).toContain('inside one of the Harness app')+ expect(d.errors[0]).toContain('inside a Harness terminal tile')expect(d.io.written()).toBe('')}})@@ -211,7 +211,7 @@ describe('remoteCommand', () => {expect(d.links).toEqual(['box-2:hunter2'])expect(d.io.written()).toContain('machine-remote-2 is not linked to this computer yet.')expect(d.io.written()).toContain('✓ Linked machine-remote-2 (fingerprint AB:CD)')- expect(d.io.written()).toContain('Switching this tile to machine-remote-2')+ expect(d.io.written()).toContain('Terminal opened on machine-remote-2. Switching this tile…')})it('an empty password, or a link the other machine refuses, stops before anything opens', async () => {@@ -241,7 +241,7 @@ describe('remoteCommand', () => {expect(await run).toBe(0)expect(d.errors).toEqual([])expect(d.io.written()).toContain('Opening a terminal on machine-remote-2')- expect(d.io.written()).toContain('Switching this tile to machine-remote-2')+ expect(d.io.written()).toContain('Terminal opened on machine-remote-2. Switching this tile…')expect(daemon.sent.map((frame) => frame.type)).toEqual(['machine_select', 'agent_create', 'machine_select', 'remote_terminal_handoff'])})@@ -262,7 +262,7 @@ describe('remoteCommand', () => {await new Promise((resolve) => setTimeout(resolve, 5))d.io.press('enter')expect(await run).toBe(0)- expect(d.io.written()).toContain('no Harness window is here')+ expect(d.io.written()).toContain('No Harness window is open here')})it('a pin the daemon does not accept is linked again, once, and the open retried', async () => {@@ -279,7 +279,7 @@ describe('remoteCommand', () => {d.io.press('enter')expect(await run).toBe(0)expect(d.links).toEqual(['box-2:hunter2'])- expect(d.io.written()).toContain('Switching this tile to machine-remote-2')+ expect(d.io.written()).toContain('Terminal opened on machine-remote-2. Switching this tile…')// And when the second link is refused too, the command says what to run.const stubborn = new FakeDaemon((socket, frame) => { if (frame.type === 'machine_select') socket.emit('close', 4404, 'NO_PEER_LINK') })const e = deps({ connect: stubborn.connect })diff --git a/cli/src/remoteCommand.ts b/cli/src/remoteCommand.tsindex 7705f5a7c..da1d56f02 100644--- a/cli/src/remoteCommand.ts+++ b/cli/src/remoteCommand.ts@@ -94,7 +94,7 @@ export function pickMachine(const draw = (): void => {if (drawn) output.write(`\x1b[${drawn}A\x1b[J`)const lines = [- ' Open a terminal on: ↑/↓ choose · Enter open · Esc cancel',+ ' Open a terminal on another machine ↑/↓ choose · Enter open · Esc cancel',...choices.map((choice, at) => {const mark = at === index ? '❯' : ' 'const status = isOnline(choice) ? 'Online' : 'Offline'@@ -115,7 +115,7 @@ export function pickMachine(if ((key.ctrl && key.name === 'c') || key.name === 'escape' || key.name === 'q') { finish(null); return }if (key.name === 'return' || key.name === 'enter') {const choice = choices[index]- if (choice && !isOnline(choice)) { note = `${choice.label} is offline — run \`harness start\` there, or choose one that is online.`; draw(); return }+ if (choice && !isOnline(choice)) { note = `${choice.label} is offline. Run \`harness start\` there, or choose an online machine.`; draw(); return }finish(choice ?? null); return}if (key.name === 'up' || key.name === 'k') index = (index - 1 + choices.length) % choices.length@@ -273,7 +273,7 @@ export function remoteFailureLine(error: unknown, machine: RemoteMachineChoice):async function linkNow(deps: RemoteCommandDeps, choice: RemoteMachineChoice): Promise<boolean> {const { output, error } = depsoutput.write(` ${choice.label} is not linked to this computer yet.\n`)- output.write(' Enter the remote password set on THAT machine (`harness remote-password set` there).\n')+ output.write(' Enter that machine\'s remote password (set there with `harness remote-password set`).\n')const password = (await deps.promptPassword(` Remote password for ${choice.label}: `)).trim()if (!password) { error(' ✗ No password entered; nothing was linked.'); return false }const linked = await deps.link(choice.machineId, password)@@ -286,8 +286,8 @@ async function linkNow(deps: RemoteCommandDeps, choice: RemoteMachineChoice): Prexport async function remoteCommand(deps: RemoteCommandDeps): Promise<number> {const { tmuxPane, output, error } = depsif (!tmuxPane || !TMUX_PANE_RE.test(tmuxPane)) {- error('`harness remote` works inside one of the Harness app\'s terminal tiles (New Harness → Terminal, or ⌘⇧T).')- error('Open one there and run it again.')+ error('`harness remote` runs inside a Harness terminal tile (⌘⇧T, or New Harness ▸ Terminal).')+ error('Open one and run it there.')return 1}if (!deps.input.isTTY || !output.isTTY) { error('`harness remote` needs a terminal to choose a machine in.'); return 1 }@@ -329,14 +329,14 @@ export async function remoteCommand(deps: RemoteCommandDeps): Promise<number> {try {const { windows } = await handoffTerminal(deps, deps.localMachineId, { tmuxPane, machineId: choice.machineId, agentId })if (windows === 0) {- output.write(` ✓ Terminal open on ${choice.label} — no Harness window is here to switch this tile; find it in the app's agent list.\n`)+ output.write(` ✓ Terminal opened on ${choice.label}. No Harness window is open here to switch this tile — find it in the app's agent list.\n`)return 0}- output.write(` ✓ Switching this tile to ${choice.label}.\n`)+ output.write(` ✓ Terminal opened on ${choice.label}. Switching this tile…\n`)return 0} catch (failure) {error(` ✗ ${remoteFailureLine(failure, choice)}`)- error(` The terminal is open on ${choice.label} all the same (agent ${agentId.slice(0, 8)}); find it in the app's agent list.`)+ error(` The terminal is open on ${choice.label} all the same (agent ${agentId.slice(0, 8)}) — find it in the app's agent list.`)return 1}}diff --git a/docs/cli.md b/docs/cli.mdindex 3ecf4098d..31f5b0150 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -22,7 +22,7 @@ works the same on a headless Linux server; the app is not required on a machine,| `harness browser-link` | Print a reusable seven-day setup link for browsers. || `harness remote-password set\|status\|clear` | This machine's persistent password for machine-to-machine links. || `harness link connect <id> [--name=<label>]` · `harness link list` · `harness link unlink <id>` | Let this machine reach another of yours, terminating E2EE here; list; unlink. |-| `harness remote` | From a terminal tile in the app: pick another of your machines (↑/↓, Enter; Online/Offline shown, offline not takeable), link it on the spot if it is not yet, open a terminal there and switch the tile to it — the shell it was typed in is ended. Only inside a Harness tile. |+| `harness remote` | From a Harness terminal tile: choose another of your machines (linking it on the spot if needed), open a terminal there and move this tile to it. || `harness grid login [--force] [--json]` · `harness grid logout` | Sign the `grid` CLI in with this computer's account, no second browser. || `harness flash [flags]` | Re-flash a plugged-in Harness device over USB. Flags pass straight to the flasher. || `harness autonomous-device discover\|status\|list\|pair\|revoke` | Pair Autonomous OS devices found on the LAN, directly, with no relay. |