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
import type { FolderSetting } from './hooks.js'
/**
* An engine whose CLI can leave work on a server of its own, shared per store (Codex's app-server). Declared
* data: core decides from it, with no worker, whether a client's conversation lives on that server at all,
* and the server's protocol is the engine worker's (facets/nativeControl.ts). Copied from the former
* lib/codexSessionLifecycle.ts, which read these facts in core before the move.
*/
export interface SharedServerContract {
/** Harness puts this first among the options of a client that owns its conversation in its own process. */
ownedFlag: string
/** A client given this option (or `<flag>=…`) works on a remote server, which no local stop reaches. */
remoteFlag: string
/** The script's basenames when an interpreter (node) runs the CLI: its options start after the script. */
scripts: readonly string[]
/** Where, in the store, the server records its process, as JSON `{ pid, processStartTime }`. */
pidFile: string
/** What the person is told when the stop cannot go on, in the engine's own words. */
messages: { unverified: string; remote: string; unidentified: string }
}
/**
* The flag that hands the engine its harness context file (a DSH's CONTEXT.md). `{file}` in an argument is
* the file's path, as a JSON string where `quote` is `json`. Applied by kit/launchArgs.ts.
*/
export interface ContextArgsTemplate {
args: readonly string[]
quote: 'json'
}
/**
* The session's variables as argv, for an engine whose commands do not inherit its process's environment.
* Each variable whose name `name` accepts becomes `flag` followed by `setting`, in which `{name}` is its name
* and `{value}` its value as a JSON string. Applied by kit/launchArgs.ts.
*/
export interface EnvArgsTemplate {
flag: string
setting: string
name: RegExp
}
/**
* The provider an engine goes back to when it leaves a grid, for an engine that keeps the provider it was
* launched with in state of its own. The person's choice is the top-level `key` of `file` in the launch's
* home (the agent's profile, else the home `home` names, as the person's shell may move it), else `fallback`.
* `{value}` in `args` is that provider. Applied by kit/launchArgs.ts; the composition is engines/launches.ts.
*/
export interface OwnProviderContract {
home: FolderSetting
file: string
key: string
fallback: string
args: readonly string[]
}
/**
* Run again, in the same pane and with the same arguments, after a startup that ended before the
* conversation opened. Told by the pane's last line, read through the daemon's tmux after the engine exits
* (so its terminal stays real throughout), and only a line printed since that run began.
*/
export interface StartupRetry {
/**
* A startup update that ended the run with `status` and asks to be started again: `line` is a regular
* expression's source for that last line. One more run follows, with no time limit, since the person may
* leave the update's prompt open first.
*/
updated: { status: number; line: string; message: string }
/**
* A transient failure: the run ended with `status`, and the last line is exactly `line`, within `withinMs`
* of the run starting. Up to `attempts` runs in all, the n-th retry after `backoffSeconds` × n; Ctrl-C
* cancels the wait. `message` may name `{attempt}`, `{attempts}` and `{delay}`.
*/
transient: { status: number; line: string; withinMs: number; attempts: number; backoffSeconds: number; message: string }
}
/**
* What the pane's script does around the engine's run, beyond the wrapper every engine gets
* (lib/engineLaunch.ts). Declared data, written into the script by kit/launchStartup.ts. A launch is session
* control, so no worker is involved: the script runs in the pane, under the daemon's own Node.
*/
export interface StartupContract {
/**
* Before every run, ask the binary's own `--help` whether it takes `sharedServer.ownedFlag`, and pass it
* first when it does: an older build lacks it. A probe that cannot answer ends the launch, saying
* `unverified`. It also gives the engine a POSIX shell to run in where the daemon has no login shell. Windows has
* none: there the daemon reads the help as it inspects the launch, and the flag goes in the argv
* (lib/windows/engineStart.ts).
*/
ownedFlag?: { unverified: string }
retry?: StartupRetry
}
/**
* The screen Harness runs an engine's TUI on: the terminal's own scrollback, or a full-screen alternate screen of
* the engine's. Every launch Harness makes applies it (kit/launchScreen.ts), whatever the person's own settings say,
* so one engine looks the same on every computer. An engine that declares none runs as the person set it up.
*
* Why: one pane is driven by a desktop window and a phone in turn, and each takeover resizes it. In the scrollback
* the history is the viewer's own and scrolls natively, and Find, selection and the phone's long-press reach all of
* it; full screen, the engine pins its prompt to the foot of the pane and owns scrolling. The scrollback serves an
* engine that lays its history out again cleanly when the pane narrows: Codex does, so Harness runs it there
* (codex/launch.ts). Claude Code does not (it printed part of its conversation twice), and Harness leaves its screen
* to the person's own setting. The keyframe re-wraps a history kept in the scrollback by word (lib/historyRewrap.ts).
*/
export interface ScreenContract {
/** Argv given to every launch, ahead of the launch's own extra arguments. */
args?: readonly string[]
/** Variables exported after the person's rc files, so neither their shell nor their profile can undo them. */
environment?: Readonly<Record<string, string>>
/** Variables removed after the person's rc files: those that would choose the other screen. */
clearEnvironment?: readonly string[]
/**
* How the engine answers a resize in the scrollback, where it does so by printing its transcript again: within
* `withinMs` of the resize it writes `clears` (it has cleared the screen and the scrollback), then the transcript,
* which the first `ends` after the clear closes. A keyframe taken right after a resize waits for that print to end,
* so a viewer never draws the cleared screen in between (lib/tmuxStream.ts `snapshot`). The end is read off the
* output, not inferred from a pause in it: an engine at work animates its status line without one.
*/
resizeRepaint?: { clears: string; ends: string; withinMs: number }
}
/**
* Where an engine keeps its own settings for a launch made now. `setting`: the folder a daemon setting names,
* unless the person's shell moves it, unless the agent has a profile of its own (Codex's CODEX_HOME).
* `variable`: the folder a variable the person's shell sets names, else their home folder, or `folder` in it
* (Claude Code's CLAUDE_CONFIG_DIR: `.claude.json` is in the home folder itself, `settings.json` in `~/.claude`).
* Resolved by lib/engineHomes.ts `launchHomeOf`.
*/
export type LaunchHome = { setting: FolderSetting } | { variable: string; otherwise: 'home' | { folder: string } }
/**
* An engine's answer to "do you trust this folder?", which it asks the first time it opens one, kept in `file`
* in its home. Harness records it only for a folder it made empty itself (the callers decide), never removes
* anything, and leaves a file it cannot safely extend as it is. Applied by kit/folderTrust.ts.
*/
export type TrustContract = { home: LaunchHome; file: string } & (
/**
* A JSON object whose `projects` map a folder to its entry, trusted where `accepted` is true. A trusted
* folder's trust covers every folder below it. A new entry starts as `entry`.
*/
| { format: 'json'; projects: string; accepted: string; entry: Readonly<Record<string, unknown>> }
/** A TOML table per folder, `[<table>."<folder>"]`, trusted where its `key` is `value`. Exact folders only. */
| { format: 'toml'; table: string; key: string; value: string }
)
/**
* The engine's question about MCP servers a folder inherits: a project file of servers (`file`, `servers` its map) in a
* folder ABOVE the one it opens, which it asks to use or not as it starts there. Its own "no", the question's default, is
* kept as `rejected` in `settings` in the folder. Harness records that same "no" for a folder it made empty itself,
* where it records the folder's trust, so its agent starts at once instead of waiting on the person: a Claude Code
* harness in a new project under the home sat at "New MCP server found in this project: argent" with its first message
* never typed, while `harness wait` read it as working (2026-10-26). A server the person decided in their user
* settings (`user`: `approved`, `rejected`, or `approveAll` on) is theirs and left alone; so is a file in the folder.
* Applied by kit/inheritedMcp.ts.
*/
export interface InheritedMcpContract {
file: string
servers: string
settings: string
rejected: string
user: { home: LaunchHome; file: string; approved: string; rejected: string; approveAll: string }
}
/**
* Making a stopped conversation's history resumable before the engine is launched on it again. Applied by
* kit/resumeRepair.ts, after the engine has stopped and before the tail moves and the engine starts.
*/
export interface ResumeRepairContract {
/**
* Where histories are: `folder` in the engine's home (the agent's profile, else every home the person moved
* and the daemon's). One is a file ending in `suffix` whose name holds the session's id, at any depth; only
* names with no `.` are folders worth entering, and at most `walk` entries are looked at. An id `id` refuses
* is never looked for.
*/
sessions: { home: { setting: FolderSetting }; folder: string; suffix: string; id: RegExp; walk: number }
/** The first record names the session: its `type`, and the field that holds the id. */
first: { type: string; id: readonly string[] }
/** The records whose items the engine replays: the item at `at`, or each item of the list there. */
items: ReadonlyArray<{ type: string; at: readonly string[]; list?: boolean }>
/**
* What is repaired in each item. `portable-reasoning`: the relay's portable_reasoning_item contract (a
* plaintext reasoning item keeps no vendor id, and its text is its summary).
*/
repair: 'portable-reasoning'
/** The private files beside the history, by suffix: the backup of what it was, and the one being written. */
backup: string
temporary: string
/** How the person, and the daemon's log, name the history file, the history and what was repaired. */
names: { file: string; history: string; items: string }
}
/**
* How an engine is told to add a line to the pull requests it opens: a harness another agent started says so
* (lib/agentAttribution.ts). Applied by kit/attribution.ts on each launch of one, its relaunches included. The
* person's choices stay theirs: the engine's own line is kept beside it, an instruction of theirs is never
* replaced, and where they hid the engine's attribution nothing is added.
*/
export type AttributionContract = SettingAttribution | InstructionAttribution
/**
* An engine with a setting for the text it adds to a pull request, in JSON settings files that a settings object
* on its command line overrides key by key (Claude Code's `attribution.pr` and `--settings`, 2.1.296). The
* setting's text replaces the engine's own line, so it is given the line the engine would have added, then ours.
*/
export interface SettingAttribution {
kind: 'setting'
/** The person's settings files, lowest precedence first: `file` in `home`, then each of `folder` in the harness's folder. */
home: LaunchHome
file: string
folder: readonly string[]
/** The setting: an object at `key` whose `field` is the pull request's text. `false` at `key` hides every line. */
key: string
field: string
/**
* An older setting that, `false`, hides every line while `key` sets none of `until` (Claude Code's
* `includeCoAuthoredBy`). Setting `field` would end that and bring back the engine's commit line, so a person
* who set it gets nothing added.
*/
legacy?: { key: string; until: readonly string[] }
/** The engine's own line, where the person set no text. */
own: string
/** The argv; `{settings}` is the settings object, as JSON. */
args: readonly string[]
/**
* The same line as an instruction (`{line}`), told with Harness's instructions (`harnessInstructions` `append`)
* whenever the setting is given: a setting is only a default, which the agent drops once its task spells out the
* pull request's body.
*/
instruction?: string
}
/**
* The engine's status line, which Harness's own command takes over at every launch to record the plan's rate limits
* the engine reports there (hook/statusline.mjs, kit/statusLine.ts), then runs the person's own status line command,
* so they see what they saw before. Claude Code's `statusLine` (2.1.316: `type: 'command'`, `command`, `padding`,
* `refreshInterval`, `hideVimModeIndicator`), given in a settings object on its command line.
*/
export interface StatusLineContract {
/** The person's settings files, lowest precedence first: `file` in `home`, then each of `folder` in the harness's folder. */
home: LaunchHome
file: string
folder: readonly string[]
/** The setting's key, and the `type` of one that runs a command (its text in `command`). */
key: string
type: string
/** The argv; `{settings}` is the settings object, as JSON. The engine keeps only the last, so a launch gives one. */
args: readonly string[]
}
/**
* An engine with no setting for its attribution's text, which it gives its model as an instruction (Codex 0.162.1:
* `<git_attribution>` in the developer message), and which takes more instructions in a config key `-c` sets
* (`developer_instructions`). `-c` replaces the person's own value, so theirs comes first and ours after it; one
* that cannot be read exactly, or one a folder's own config sets, is left alone and nothing is added.
*/
export interface InstructionAttribution {
kind: 'instruction'
/** The person's config: `file` in the agent's profile, else the home `home` names. */
home: LaunchHome
file: string
/** A folder's own config, looked for in the harness's folder and each folder above it, up to the home folder. */
folder: string
/** The top-level key the instructions are in. */
key: string
/** What the model is told; `{line}` is the line. */
instruction: string
/** The argv; `{value}` is the instructions, as a JSON string, which TOML reads as the same string. */
args: readonly string[]
}
/**
* The flags that give ONE session its model and effort, so that nothing is written to the person's own engine
* settings (Claude Code's `/model` and `/effort` commands are saved there as the new default). `{value}` in an
* argument is the model or the effort. `efforts` are the levels the effort flag takes; any other is refused.
* Applied by lib/launchModel.ts.
*/
export interface ModelArgsContract {
model: readonly string[]
effort: readonly string[]
efforts: readonly string[]
}
/** Literal argv contracts copied from the existing launch paths. No engine version behavior changes. */
export interface EngineLaunch {
permissionModes: Readonly<Record<string, readonly string[]>>
bypassPermission: string[]
firstPromptArgs: readonly string[]
resumeArgs: string[]
/** How a new session is launched with a model and effort of its own, for this session only. */
modelArgs?: ModelArgsContract
forkArgs: { lead: string[]; after?: string[] }
instructionFiles: readonly string[]
contextArgs?: ContextArgsTemplate
envArgs?: EnvArgsTemplate
sharedServer?: SharedServerContract
ownProvider?: OwnProviderContract
/** A conversation stays on the provider it was started on: the engine refuses to resume it on another, so a move
* between a grid and the engine's own login continues it in a fork (`forkArgs`) instead (core/agents/retarget.ts). */
providerBoundConversations?: true
startup?: StartupContract
/** The screen the engine's TUI runs on, where Harness chooses it; applied to every launch (kit/launchScreen.ts). */
screen?: ScreenContract
/** Arguments for a session the Swarm started, never for a person's own (lib/swarmEngineArgs.ts). */
swarmArgs?: readonly string[]
/** The instruction file Harness writes its own notes into (a harness's bootstrap, the saved APIs); else AGENTS.md. */
instructionFile?: string
/** The line, in that file, that has the engine read `file` too (Claude Code's `@AGENTS.md` import). */
instructionImport?: { file: string; line: string }
trust?: TrustContract
/** Recorded with `trust`, for the same folders (kit/inheritedMcp.ts). */
inheritedMcp?: InheritedMcpContract
resumeRepair?: ResumeRepairContract
attribution?: AttributionContract
statusLine?: StatusLineContract
/** How the engine is told, as it starts, that it runs in Harness and how to use it (lib/agentAttribution.ts). */
harnessInstructions?: HarnessInstructionsContract
}
/**
* Where an engine takes a few lines of instructions on its command line: appended to its system prompt (`append`,
* Claude Code's `--append-system-prompt`; `{text}` is the text), or beside its attribution instruction, in the one
* config value both live in (`attribution`, Codex's `developer_instructions`: a second `-c` of the same key would
* replace the first, and the person's own value).
*/
export type HarnessInstructionsContract = ({ kind: 'append'; args: readonly string[] } | { kind: 'attribution' }) & {
/** Said after Harness's instructions to this engine's agents alone: what about the engine changes how they use them. */
also?: string
}