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
/**
* git and gh for a Swarm agent doing another person's project work, through the Harness GitHub App
* (docs/swarm-github-app.md) instead of this machine owner's own GitHub login.
*
* Everything reaches the agent as environment variables, because those survive what its shells do: Codex runs every
* command in a login shell, Claude Code replays the person's startup files, and on a Mac both put Homebrew's folders
* back in front of PATH, so a wrapper placed first on PATH would be passed over. So:
*
* - git reads `GIT_CONFIG_PARAMETERS` (the variable `git -c` itself uses, above every config file): for github.com its
* credential helpers are reset to Harness's alone, which asks the daemon for the task's token
* (superTabs/gitCredential.ts) and answers only for the task's repository; ssh remotes of github.com are fetched and
* pushed over https, so no ssh key of the owner is used; and `core.hooksPath` names hooks that run the repository's
* own hook first, then add the attribution trailers to each commit message.
* - gh reads `GH_CONFIG_DIR`, a folder of this session's own whose token the daemon keeps fresh (superTabs/github.ts)
* and empties when the task ends. The owner's gh configuration is never read.
*
* The variable `GIT_CONFIG_KEY_n` is not used: Codex leaves out of its commands every variable whose name contains KEY.
*/
import { accessSync, chmodSync, constants, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs'
import { delimiter, join } from 'node:path'
import { env } from '../config/env.js'
import { daemonCommand } from './daemonCommand.js'
import { readAuthSession } from './authSession.js'
import { computerId } from './daemonState.js'
/** Every hook git runs from `core.hooksPath`, so a repository's own hooks all still run. */
export const GIT_HOOK_NAMES = ['applypatch-msg', 'pre-applypatch', 'post-applypatch', 'pre-commit', 'pre-merge-commit', 'prepare-commit-msg',
'commit-msg', 'post-commit', 'pre-rebase', 'post-checkout', 'post-merge', 'pre-push', 'pre-receive', 'update', 'proc-receive',
'post-receive', 'post-update', 'reference-transaction', 'push-to-checkout', 'pre-auto-gc', 'post-rewrite', 'sendemail-validate',
'p4-changelist', 'p4-prepare-changelist', 'p4-post-changelist', 'p4-pre-submit', 'post-index-change'] as const
/** Variables that would put another GitHub login in front of the session's own (gh reads them before its config). */
export const SWARM_GITHUB_CLEAR_ENV = ['GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN']
/** A word for a POSIX shell. */
export const shellWord = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`
export const swarmGitHubRoot = (dataDir: string) => join(dataDir, 'swarm-github')
const SESSION_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
/** This session's own folder: its gh configuration and its commit trailers. Null for a key unfit for a path. */
export function swarmGitHubSessionDir(dataDir: string, key: string): string | null {
return SESSION_KEY.test(key) ? join(swarmGitHubRoot(dataDir), 'sessions', key) : null
}
/** What git reads for the session (see the file comment). [identity]: the session's own config file, which names who its
* commits are by once the server says (writeSessionGitHub); git skips an include whose file is not there. */
export function gitConfigParameters(helper: string, hooks: string, identity?: string): string {
const entries: Array<[string, string]> = [
// An empty helper empties the list of helpers read so far, from every config file: only Harness's is left.
['credential.https://github.com.helper', ''],
['credential.https://github.com.helper', `!${shellWord(helper)}`],
// git sends the repository's path to the helper, which answers only for the task's repository.
['credential.https://github.com.usehttppath', 'true'],
['url.https://github.com/.insteadof', '[email protected]:'],
['url.https://github.com/.insteadof', 'ssh://[email protected]/'],
['core.hookspath', hooks],
...(identity ? [['include.path', identity] as [string, string]] : []),
]
return entries.map(([key, value]) => `${shellWord(key)}=${shellWord(value)}`).join(' ')
}
/** Whether a program git-lfs that git can run is on [path] (a PATH value). */
export function hasGitLfs(path: string | undefined): boolean {
const name = process.platform === 'win32' ? 'git-lfs.exe' : 'git-lfs'
return (path ?? '').split(delimiter).some(dir => {
if (!dir) return false
try { const file = join(dir, name); accessSync(file, constants.X_OK); return statSync(file).isFile() } catch { return false }
})
}
/**
* The environment for the git a machine runs itself to prepare a Swarm agent's folder before the agent exists: the clone
* and the fetch of the default branch (superTabs/projectFolder.ts), with [token], a read-only Harness GitHub App token for
* the project's one repository. Nothing of the machine owner's git setup takes part: their global and system config are
* not read (credential helpers, a rewrite of https to ssh, an http header), the helpers git has so far are emptied for
* Harness's alone, ssh remotes of github.com go over https, and nothing prompts. The token is in this environment only,
* read by the helper from `HARNESS_SWARM_GIT_TOKEN`, never written to disk or put on a command line.
*/
export function swarmGitPrepareEnv(token: string, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
if (!TOKEN.test(token)) throw new Error('The Harness GitHub App token is not in the form GitHub gives.')
const env: NodeJS.ProcessEnv = { ...base }
// Config from the environment, a prompt program, or an ssh setup of the owner's would put their login back in.
for (const key of Object.keys(env)) if (/^GIT_CONFIG_(KEY|VALUE)_\d+$/.test(key)) delete env[key]
for (const key of ['GIT_CONFIG_COUNT', 'GIT_CONFIG', 'GIT_ASKPASS', 'SSH_ASKPASS', 'GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_DIR', 'GIT_WORK_TREE',
...SWARM_GITHUB_CLEAR_ENV]) delete env[key]
const helper = '!f() { test "$1" = get || return 0; echo username=x-access-token; echo "password=$HARNESS_SWARM_GIT_TOKEN"; }; f'
const entries: Array<[string, string]> = [
['credential.helper', ''],
['credential.https://github.com.helper', ''],
['credential.https://github.com.helper', helper],
['url.https://github.com/.insteadof', '[email protected]:'],
['url.https://github.com/.insteadof', 'ssh://[email protected]/'],
// Large files still arrive as git-lfs would bring them, when it is installed: its filter is in the global config skipped
// above. Only then: a filter naming a missing git-lfs failed Apple git's checkout of lampOS (MACs-Mac-Studio, 2026-11-03).
...(hasGitLfs(env.PATH ?? env.Path) ? [
['filter.lfs.process', 'git-lfs filter-process'],
['filter.lfs.clean', 'git-lfs clean -- %f'],
['filter.lfs.smudge', 'git-lfs smudge -- %f'],
] as Array<[string, string]> : []),
]
return {
...env,
GIT_CONFIG_GLOBAL: '/dev/null',
GIT_CONFIG_NOSYSTEM: '1',
GIT_CONFIG_PARAMETERS: entries.map(([key, value]) => `${shellWord(key)}=${shellWord(value)}`).join(' '),
GIT_TERMINAL_PROMPT: '0',
GCM_INTERACTIVE: 'Never',
GIT_SSH_COMMAND: 'ssh -oBatchMode=yes -oConnectTimeout=20',
HARNESS_SWARM_GIT_TOKEN: token,
}
}
export function credentialHelperScript(input: { command: string; port: number; machineId: string; dataDir: string }): string {
return '#!/bin/sh\n'
+ '# Written by Harness for Swarm agents\' git (docs/swarm-github-app.md); rewritten as agents start.\n'
+ `ADAPTER_DATA_DIR=${shellWord(input.dataDir)} exec ${input.command} git-credential --port ${input.port} --machine ${shellWord(input.machineId)} "$@"\n`
}
/** One script for every hook: the repository's own hook first (found with Harness's settings left out); then, for a
* commit message that has words in it, each trailer the message does not already have, anywhere in it (an amend keeps one
* of each). An empty message is left alone so that it still aborts the commit. */
export function hookScript(input: { hooks: string; helper: string }): string {
return `#!/bin/sh
# Written by Harness for Swarm agents (docs/swarm-github-app.md): runs this repository's own hook, then adds to each
# commit message who the work is for and which agent and machine did it.
ours=${shellWord(input.hooks)}
name=\${0##*/}
own=$(GIT_CONFIG_PARAMETERS= git rev-parse --git-path hooks 2>/dev/null)
if [ -n "$own" ] && [ -x "$own/$name" ] && [ "$(cd "$own" 2>/dev/null && pwd -P)" != "$(cd "$ours" && pwd -P)" ]; then
case $name in
prepare-commit-msg|commit-msg) "$own/$name" "$@" || exit $? ;;
*) exec "$own/$name" "$@" ;;
esac
fi
case $name in prepare-commit-msg|commit-msg) ;; *) exit 0 ;; esac
msg=$1
dir=$HARNESS_SWARM_GITHUB_DIR
[ -n "$msg" ] && [ -f "$msg" ] && [ -n "$dir" ] || exit 0
[ -n "$(git stripspace --strip-comments < "$msg" 2>/dev/null)" ] || exit 0
[ -s "$dir/trailers" ] || ${shellWord(input.helper)} trailers >/dev/null 2>&1
[ -s "$dir/trailers" ] || exit 0
set --
while IFS= read -r line || [ -n "$line" ]; do
[ -n "$line" ] && ! grep -qxF -- "$line" "$msg" && set -- "$@" --trailer "$line"
done < "$dir/trailers"
[ $# -gt 0 ] && git interpret-trailers --in-place --if-exists addIfDifferent "$@" "$msg" 2>/dev/null
exit 0
`
}
/** Writes [text] to [file] unless it already says exactly that; never through a half-written file. */
function writeIfChanged(file: string, text: string, mode: number): void {
try { if (readFileSync(file, 'utf8') === text) { chmodSync(file, mode); return } } catch { /* absent: written below */ }
const next = `${file}.${process.pid}.next`
writeFileSync(next, text, { mode })
chmodSync(next, mode)
renameSync(next, file)
}
export interface SwarmGitHubTools { dataDir: string; command: string; port: number; machineId: string }
const defaultTools = (): SwarmGitHubTools => ({ dataDir: env.ADAPTER_DATA_DIR, command: daemonCommand(), port: env.PORT,
machineId: readAuthSession()?.machineId || computerId() })
/** The helper and the hooks, shared by every session on this machine, written for this daemon's CLI. */
export function writeSwarmGitHubTools(tools: SwarmGitHubTools): { helper: string; hooks: string } {
const root = swarmGitHubRoot(tools.dataDir)
const bin = join(root, 'bin'), hooks = join(root, 'hooks')
for (const dir of [root, bin, hooks]) mkdirSync(dir, { recursive: true, mode: 0o700 })
const helper = join(bin, 'git-credential')
writeIfChanged(helper, credentialHelperScript(tools), 0o700)
const script = hookScript({ hooks, helper })
for (const name of GIT_HOOK_NAMES) writeIfChanged(join(hooks, name), script, 0o700)
return { helper, hooks }
}
const GH_CONFIG = 'version: "1"\n'
/** GitHub's token formats, the stateless installation token (ghs_APPID_JWT, about 520 characters, with dots and dashes)
* among them, and nothing that could break out of the YAML around it or a shell. */
const TOKEN = /^[A-Za-z0-9_][A-Za-z0-9_.-]{19,4095}$/
/** Who a session's commits are by, as the server names the Harness GitHub App's bot account; nothing else is written. */
/** Who a Team account's commits are by: "Harness" (2026-11-02), or an older backend's name for the app's bot account. */
const COMMIT_NAME = /^(?:Harness by Autonomous|Harness|[a-z0-9][a-z0-9-]{0,99}\[bot\])$/
const COMMIT_EMAIL = /^(?:noreply@autonomous\.ai|[0-9]{1,20}\+[a-z0-9][a-z0-9-]{0,99}\[bot\]@users\.noreply\.github\.com)$/
/**
* Revoke a Harness GitHub App installation token with the token itself (GitHub's `DELETE /installation/token`): the
* read-only one a machine cloned a teammate's project with, done with once the clone and the fetch are (local Team account
* run, 2026-10-28: it stayed good for its hour). Best effort: a token GitHub does not revoke still expires within the hour.
*/
export async function revokeGitHubToken(token: string, send: typeof fetch = fetch): Promise<void> {
if (!TOKEN.test(token)) return
const answer = await send('https://api.github.com/installation/token', { method: 'DELETE', signal: AbortSignal.timeout(10_000),
headers: { Accept: 'application/vnd.github+json', Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'harness' } })
if (answer.status !== 204 && answer.status !== 401) throw new Error(`GitHub answered ${answer.status} to revoking the token`)
}
/** The session's gh login: [token] for github.com, or none. And, when given, the trailers its commits get and who they are
* by ([commitAs]: the app's bot account, which the server gives a Harness Team account, as it has no git identity of its
* own: its commits read "Harness Team <harnessteam@<host>.local>" before, PR #1934). Without one, git's own stands. */
export function writeSessionGitHub(dir: string, token: string | null, trailers?: readonly string[], commitAs?: unknown): void {
const gh = join(dir, 'gh')
mkdirSync(gh, { recursive: true, mode: 0o700 })
if (!existsSync(join(gh, 'config.yml'))) writeIfChanged(join(gh, 'config.yml'), GH_CONFIG, 0o600)
const hosts = token && TOKEN.test(token)
? `github.com:\n users:\n x-access-token:\n oauth_token: ${token}\n git_protocol: https\n oauth_token: ${token}\n user: x-access-token\n`
: '{}\n'
writeIfChanged(join(gh, 'hosts.yml'), hosts, 0o600)
if (trailers) {
const lines = trailers.filter(line => /^[A-Za-z][A-Za-z0-9-]*: [^\r\n]+$/.test(line) && line.length <= 300)
writeIfChanged(join(dir, 'trailers'), lines.map(line => `${line}\n`).join(''), 0o600)
}
if (commitAs !== undefined) {
const { name, email } = (commitAs && typeof commitAs === 'object' ? commitAs : {}) as { name?: unknown; email?: unknown }
const file = join(dir, 'gitconfig')
if (typeof name === 'string' && COMMIT_NAME.test(name) && typeof email === 'string' && COMMIT_EMAIL.test(email)) {
writeIfChanged(file, `[user]\n\tname = ${name}\n\temail = ${email}\n`, 0o600)
} else rmSync(file, { force: true })
}
}
/**
* The launch of a Swarm session that uses the app ([key]: its session label, `SwarmSkill.key`): its environment, and the
* variables to clear from what it inherits. Writes the shared tools and the session's folder first. Null for a key unfit
* for a path. On Windows, Git for Windows runs these shell scripts through its own sh: tried on Git 2.55, with a space in
* the path, for the helper, the hooks and the commit identity.
*/
export function swarmGitHubLaunch(key: string, tools: SwarmGitHubTools = defaultTools()):
{ env: Record<string, string>; clearEnv: string[] } | null {
const dir = swarmGitHubSessionDir(tools.dataDir, key)
if (!dir) return null
const { helper, hooks } = writeSwarmGitHubTools(tools)
if (!existsSync(join(dir, 'gh', 'hosts.yml'))) writeSessionGitHub(dir, null)
// Marked as just used: a start held before its session is registered must not look like a folder left behind
// (superTabs/github.ts removes those once untouched for 15 minutes; review of #1998).
const now = new Date()
utimesSync(dir, now, now)
return {
env: {
GIT_CONFIG_PARAMETERS: gitConfigParameters(helper, hooks, join(dir, 'gitconfig')),
// A credential the helper cannot give fails at once instead of waiting on a prompt nobody answers in an agent's pane.
GIT_TERMINAL_PROMPT: '0',
GH_CONFIG_DIR: join(dir, 'gh'),
GH_PROMPT_DISABLED: '1',
GH_NO_UPDATE_NOTIFIER: '1',
HARNESS_SWARM_GITHUB_DIR: dir,
},
clearEnv: [...SWARM_GITHUB_CLEAR_ENV],
}
}