Skip to content

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.

CLI: every new terminal tile opens with its guide, in fewer words

0xken15b484c3c6832a
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 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 Desktop
harness 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 it
harness 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.overrides
const 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 both
diff --git a/cli/src/lib/engineLaunch.spec.ts b/cli/src/lib/engineLaunch.spec.ts
index 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.ts
index 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.ts
index 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.ts
index 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 } = deps
output.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): Pr
export async function remoteCommand(deps: RemoteCommandDeps): Promise<number> {
const { tmuxPane, output, error } = deps
if (!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.md
index 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. |