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
/**
* The Harness Team account's own gh, installed by its own daemon, in its own home.
*
* A teammate's agent opens its pull request with gh, signed in as the Harness GitHub App for that session alone
* (lib/swarmGitHub.ts `GH_CONFIG_DIR`). The team account had only its owner's Homebrew to find gh in, and a Homebrew
* another account cannot read (/opt/homebrew/bin mode 770 on 2026-10-28) answered "permission denied": the Builder of
* PR #1934 fell back to GitHub's API by hand. So the team daemon installs gh itself when it has none it can run, as it does
* tmux (team/tmux.ts): GitHub's own release of it, checked against the checksum pinned here, in its own home. No password.
*
* On Linux the same, from GitHub's tarball for the computer's architecture.
*
* A newer gh is a new version and checksums here, from the release's `gh_<version>_checksums.txt`.
*/
import { execFile } from 'node:child_process'
import { existsSync, mkdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { runPowershell } from '../lib/windows/powershell.js'
import { untarGz } from './tmux.js'
import { WINDOWS_GH_BUILDS, windowsUnzipScript } from './windowsTeam.js'
export interface GhBuild { version: string; url: string; sha256: string; size: number; archiveRoot: string; format: 'zip' | 'tar.gz' }
const GH_VERSION = '2.103.3'
const release = (system: 'macOS' | 'linux', arch: string, sha256: string, size: number): GhBuild => {
const format = system === 'linux' ? 'tar.gz' : 'zip'
return {
version: GH_VERSION, sha256, size, archiveRoot: `gh_${GH_VERSION}_${system}_${arch}`, format,
url: `https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_${system}_${arch}.${format}`,
}
}
/** GitHub's macOS builds of gh, by `process.arch`. */
export const GH_BUILDS: Readonly<Record<string, GhBuild>> = {
arm64: release('macOS', 'arm64', 'd700207eae9ae98fe2b89535c2c087c07823d4628c56364695a5a07ef311c062', 14_106_091),
x64: release('macOS', 'amd64', 'a2f86418f4350ae6e9ec60d5000bdf7665728436946a97fc27fe50e6ae752682', 15_702_601),
}
/** GitHub's Linux builds of gh, by `process.arch`: tarballs, from the same release's checksums and sizes. */
export const GH_LINUX_BUILDS: Readonly<Record<string, GhBuild>> = {
arm64: release('linux', 'arm64', 'ee32df2323c8847f5fac6cb6b4b69ca75828e9329a8f22f677021f7b3306ce63', 13_661_485),
x64: release('linux', 'amd64', '4c806978ffce1cec70853302a56d70ac6da4f19bae7adca4e1a8ab00633dd91d', 15_031_972),
}
/** The pinned build for this system, or undefined where none is. */
export function ghBuildFor(platform: NodeJS.Platform, arch: string): GhBuild | undefined {
const builds: Readonly<Record<string, GhBuild>> | null = platform === 'darwin' ? GH_BUILDS : platform === 'linux' ? GH_LINUX_BUILDS
: platform === 'win32' ? WINDOWS_GH_BUILDS : null
return builds && Object.hasOwn(builds, arch) ? builds[arch] : undefined
}
/**
* Where a build's gh is once unpacked, and what to unpack it into. GitHub's Windows zip holds `bin\gh.exe` at its top with
* no folder around it (./windowsTeam.ts), so it is unpacked into a folder of that name; the others hold one.
*/
const ghLayout = (build: GhBuild, staging: string) => 'binary' in build
? { into: join(staging, build.archiveRoot), binary: join(build.archiveRoot, 'bin', 'gh.exe') }
: { into: staging, binary: join(build.archiveRoot, 'bin', 'gh') }
export type TeamGhOutcome = 'not-team' | 'present' | 'installed' | 'unsupported' | 'failed'
export interface TeamGhDeps {
/** Whether this daemon is a Mac's Harness Team account. */
team(): boolean
platform: NodeJS.Platform
arch: string
/** The gh binaries an agent here would find (its own, on PATH, Homebrew's): any that runs is enough. */
candidates(): string[]
runs(binary: string): Promise<boolean>
/** The archive's bytes, checked against its sha256 (lib/selfUpdate.ts `downloadVerified`). */
download(build: GhBuild): Promise<Buffer>
/** Unpacks a .zip into a folder. */
unzip(archive: string, into: string): Promise<void>
/** `~/.harness/runtime` and `~/.local/bin` of this account. */
runtimeDir: string
binDir: string
log(line: string): void
}
/** Installs gh in the team account when it has none it can run. Never throws. */
export async function ensureTeamGh(deps: TeamGhDeps): Promise<TeamGhOutcome> {
try {
if (!deps.team()) return 'not-team'
for (const binary of deps.candidates()) if (await deps.runs(binary)) return 'present'
const build = ghBuildFor(deps.platform, deps.arch)
if (!build) {
deps.log(`team: no gh build is pinned for ${deps.platform}-${deps.arch}; teammates' agents open pull requests through GitHub's API`)
return 'unsupported'
}
const target = join(deps.runtimeDir, build.archiveRoot)
const layout = ghLayout(build, '')
const binary = join(deps.runtimeDir, layout.binary)
if (!existsSync(binary)) {
mkdirSync(deps.runtimeDir, { recursive: true, mode: 0o700 })
const staging = join(deps.runtimeDir, `.gh-staging-${process.pid}`)
rmSync(staging, { recursive: true, force: true })
mkdirSync(staging, { recursive: true, mode: 0o700 })
try {
const archive = join(staging, `gh.${build.format}`)
writeFileSync(archive, await deps.download(build), { mode: 0o600 })
await deps.unzip(archive, ghLayout(build, staging).into)
if (!existsSync(join(staging, layout.binary))) throw new Error(`the gh archive has no ${layout.binary}`)
rmSync(target, { recursive: true, force: true })
renameSync(join(staging, build.archiveRoot), target)
} finally {
rmSync(staging, { recursive: true, force: true })
}
}
if (!await deps.runs(binary)) throw new Error(`the installed gh does not run here: ${binary}`)
// On the PATH the team daemon gives its agents, and last on a login shell's: an unreadable Homebrew before it is skipped.
mkdirSync(deps.binDir, { recursive: true })
if (deps.platform === 'win32') {
// A link needs a privilege on Windows: a command file in its place, which cmd.exe and PowerShell find as `gh`.
writeFileSync(join(deps.binDir, 'gh.cmd'), `@"${binary}" %*\r\n`)
} else {
rmSync(join(deps.binDir, 'gh'), { force: true })
symlinkSync(binary, join(deps.binDir, 'gh'))
}
deps.log(`team: installed gh ${build.version} for the Harness Team account → ${target}`)
return 'installed'
} catch (error) {
deps.log(`team: could not install gh for the Harness Team account: ${error instanceof Error ? error.message : String(error)}`)
return 'failed'
}
}
/** Whether [binary] runs and says it is gh. */
export const ghRunsAt = (binary: string) => new Promise<boolean>((resolve) => {
execFile(binary, ['--version'], { timeout: 5_000, env: { ...process.env, GH_NO_UPDATE_NOTIFIER: '1' } },
(error, stdout) => resolve(!error && /^gh version \S+/.test(String(stdout).trim())))
})
/** Unpacks a .zip with the system's ditto, which every Mac has, Linux's .tar.gz with the system's tar, and on Windows a .zip
* with Windows PowerShell's Expand-Archive. */
export const unzipArchive = (archive: string, into: string, platform: NodeJS.Platform = process.platform): Promise<void> => archive.endsWith('.tar.gz')
? untarGz(archive, into)
: platform === 'win32' ? new Promise<void>((resolve, reject) => {
const query = windowsUnzipScript(archive, into)
if (runPowershell(query.script, query.inputs).status === 0) resolve()
else reject(new Error(`could not unpack ${archive}`))
})
: new Promise<void>((resolve, reject) => {
execFile('/usr/bin/ditto', ['-x', '-k', archive, into], { timeout: 60_000 }, (error) => error ? reject(new Error(`could not unpack ${archive}`)) : resolve())
})