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
/**
* Spawning the `claude` CLI for one turn.
*
* The invocation mirrors `apps/agent-node/brain/src/prefrontal/process.ts:444-463` — the flags are
* infrastructural, and the user's message is passed VERBATIM. No wrapper text, no prepended hints.
*
* ⚠ This runs with `--dangerously-skip-permissions`: Claude executes tools without asking. That is a
* deliberate choice for this example (it matches the product's `auto` autonomy) and it means the
* agent can modify anything under its `cwd`. Point `agents.json` at a directory you are happy to
* hand over. See README.md.
*/
import { spawn, type ChildProcess } from 'node:child_process'
import { createInterface } from 'node:readline'
import { anthropicSpawnEnv, type AnthropicEnv } from './config.js'
import type { StreamLine } from './mapper.js'
export interface TurnOptions {
claudeBin: string
cwd: string
/** The user's text, passed through untouched. */
text: string
/** Present on every turn after the first in a session. */
resumeSessionId?: string
model?: string
/** The endpoint and credential to run against. Absent ⇒ the CLI uses its own local login. */
anthropic?: AnthropicEnv
signal?: AbortSignal
}
export interface TurnHandle {
/** Resolves on exit. CLI failures arrive through `onLine`; input delivery failures set `inputError`. */
done: Promise<{ code: number | null; killed: boolean; inputError?: string }>
kill: () => void
}
/**
* Start a turn. `onLine` receives each parsed stdout line in order.
*
* Unparsable stdout is skipped rather than thrown on: the CLI is free to print things that are not
* our JSON, and a stray line must not kill a turn.
*/
export function runTurn(opts: TurnOptions, onLine: (line: StreamLine) => void, onStderr?: (chunk: string) => void): TurnHandle {
const args = [
...(opts.model ? ['--model', opts.model] : []),
'--print',
'--verbose',
'--output-format', 'stream-json',
'--input-format', 'stream-json',
'--include-partial-messages',
'--dangerously-skip-permissions',
...(opts.resumeSessionId ? ['--resume', opts.resumeSessionId] : []),
]
const child = spawn(opts.claudeBin, args, {
cwd: opts.cwd,
// Its own process group, so cancelling kills the tools it started too. A bare child.kill()
// leaves those orphaned — the same reason brain uses kill(-pid) in oneshot.ts.
detached: true,
stdio: ['pipe', 'pipe', 'pipe'],
// Credentials LAST, so a configured endpoint wins over whatever the parent shell happens to
// export. Absent, this spreads to nothing and the CLI authenticates exactly as it did before.
env: { ...process.env, ...anthropicSpawnEnv(opts.anthropic) },
})
let killed = false
let inputError: string | undefined
const kill = (): void => {
if (killed || child.exitCode !== null) return
killed = true
killGroup(child)
}
opts.signal?.addEventListener('abort', kill, { once: true })
const failInput = (err: Error): void => {
inputError = `could not write input to claude: ${err.message}`
// A broken pipe is an execution failure, not a user cancellation.
killGroup(child)
}
child.stdin?.on('error', failInput)
if (child.stdout) {
const rl = createInterface({ input: child.stdout, crlfDelay: Infinity })
rl.on('line', (raw) => {
const trimmed = raw.trim()
if (!trimmed) return
let parsed: StreamLine
try {
parsed = JSON.parse(trimmed) as StreamLine
} catch {
return // not our JSON — ignore rather than fail the turn
}
onLine(parsed)
})
}
if (child.stderr && onStderr) {
child.stderr.on('data', (chunk: Buffer) => onStderr(chunk.toString()))
}
// The user's message, verbatim, in the input-format stream-json envelope (brain: process.ts:809).
try {
child.stdin?.write(`${JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text: opts.text }] } })}\n`)
child.stdin?.end()
} catch (err) {
failInput(err instanceof Error ? err : new Error(String(err)))
}
const done = new Promise<{ code: number | null; killed: boolean; inputError?: string }>((resolve) => {
let settled = false
const finish = (code: number | null): void => {
if (settled) return
settled = true
opts.signal?.removeEventListener('abort', kill)
resolve({ code, killed, ...(inputError ? { inputError } : {}) })
}
child.on('close', finish)
child.on('error', () => finish(null))
})
return { done, kill }
}
function killGroup(child: ChildProcess, signal: NodeJS.Signals = 'SIGKILL'): void {
if (child.pid == null || child.exitCode !== null) return
try {
process.kill(-child.pid, signal) // negative pid = the whole group
} catch {
try { child.kill(signal) } catch { /* already gone */ }
}
}