headlesscode

headlesscode runs the Zoo Code agent loop from a Node.js process, without a VS Code window. Run one task directly, launch parallel workers in Git worktrees, or use the NVIDIA OpenShell provider for sandboxed sessions.

Use it for	What it does
One repository task	Reads project modes and instructions, edits files, runs commands, and reports a result.
Parallel issue work	Splits GitHub issues into Git worktrees, runs workers, monitors completion, and reviews changes.
Intake automation	Watches a GitHub label and starts bounded batches of work.
OpenShell sessions	Runs worker and review sessions in disposable clones, then validates and imports results after sandbox deletion.
Harness experiments	Runs a bounded recursive self-improvement loop against an external evaluator.

Security

Default-allow arbitrary command execution. By default, headlesscode runs shell commands with the invoking user's privileges. It can read and modify files, including credentials such as ~/.ssh and ~/.aws, without approval prompts. Use it only with trusted tasks and isolate it with a container, VM, or dedicated user when untrusted content is involved. The optional permissions layer is defense in depth, not a security boundary. See SECURITY.md.

OpenShell runs each session in a disposable Git clone mounted at /workspace; the host worktree and harness control files are not mounted. After the sandbox is deleted, HeadlessCode validates a Git bundle and imports the result into the host worktree. The gateway must support Docker bind mounts and must see the configured scratch root at the same absolute path as the host. See the OpenShell guide for setup and security details. This integration does not configure NVIDIA Sentry or hardware monitoring.

Quick start

Requires Node.js 22.19 or newer. Install globally or run with npx:

npm install -g headlesscode
# or
npx headlesscode --task "Fix the bug in src/index.ts" --workspace /path/to/repo

For a real model call, set the OpenRouter key. --dry-run does not need a key.

Variable	Required	Purpose
HEADLESSCODE_OPENROUTER_API_KEY	For OpenRouter calls	OpenRouter API key.
OPENROUTER_MODEL	No	Default model; deepseek/deepseek-v4-flash-0731. --model overrides it.
OPENROUTER_HTTP_REFERER	No	OpenRouter application referer header.
OPENROUTER_APP_TITLE	No	OpenRouter application title header.
HEADLESSCODE_WORKSPACE_ROOT	No	Default workspace; otherwise the current directory.

export HEADLESSCODE_OPENROUTER_API_KEY=sk-or-...
headlesscode --task "Fix the bug in src/index.ts" --workspace /path/to/repo

For a source checkout:

git clone https://github.com/Capsize-Games/headlesscode.git
cd headlesscode
npm install
node bin/headlesscode.mjs --task "Fix the bug in src/index.ts" --workspace /path/to/repo

To install a headlesscode wrapper on your PATH, run scripts/install-cli.sh. It writes to ~/.local/bin by default (override with HEADLESSCODE_BIN_DIR) and runs this checkout's local tsx. Re-run it if you move the checkout.

Check project instructions without calling a model

--dry-run builds the system prompt and validates project configuration. It prints the prompt and a summary of loaded modes, tools, and prompt size. A successful exit means prompt building and mode/rules loading succeeded.

headlesscode --dry-run --mode code --workspace /path/to/repo

Project .roomodes, .roo/rules-<slug>/, and AGENTS.md instructions are loaded by the prompt builder when applicable. The selected mode controls which tools are exposed. See Architecture for the relevant code.

OpenShell

Build the worker image and import the OpenRouter provider profile once. Configure a Docker-backed OpenShell gateway with driver-config and bind-mount support; keep that gateway restricted to trusted operators.

# Run these commands from a HeadlessCode source checkout.
docker build -f docker/OpenShell.Dockerfile -t headlesscode-openshell:local .
openshell profile import -f shared/openshell/headlesscode-openrouter.yaml

export HEADLESSCODE_OPENROUTER_API_KEY=sk-or-...
export HEADLESSCODE_OPENSHELL_POLICY="$PWD/shared/openshell/headlesscode-policy.yaml"
headlesscode orchestrate --repo /path/to/repo --issue 42 \
  --execution-provider openshell

Each worker gets an independent clone and a temporary result directory. Neither bind source is the host worktree. After the sandbox is deleted, HeadlessCode imports a verified Git bundle into the host branch. The default scratch root is ~/.local/share/headlesscode/openshell-sessions; create it before starting the gateway and bind-mount it into the gateway container at the same absolute path. If you choose another root, set HEADLESSCODE_OPENSHELL_SCRATCH_ROOT and mount that host directory into the gateway container at the same path. Project data and shared instructions are copied into the scratch tree and mounted separately. The writable scratch checkpoint store supports checkpoints during a session and is discarded at teardown. Opt-in memory uses a scratch snapshot and merges validated JSONL records after sandbox deletion. No OpenRouter key is passed as a normal sandbox environment argument; OpenShell injects the imported provider credential.

headlesscode watch accepts the same --execution-provider openshell option. OpenShell applies to worker, plan-first, continuation, reviewer, QA, and rework sessions. The one-off headlesscode openshell-session command runs a single task and keeps its host worktree for review. Set up a gateway callback address that the sandbox's Docker bridge can reach; keep the client endpoint loopback only when possible. Read the OpenShell guide before adapting the sample gateway or filesystem policy.

Setting	Default	Meaning
--execution-provider	local	orchestrate/watch runtime: local or openshell. Also settable with HEADLESSCODE_EXECUTION_PROVIDER.
HEADLESSCODE_OPENSHELL_POLICY	No default	Base OpenShell policy YAML; required for OpenShell sessions.
HEADLESSCODE_OPENSHELL_IMAGE	headlesscode-openshell:local	Sandbox image.
HEADLESSCODE_OPENSHELL_PROVIDERS	headlesscode-openrouter	Comma-separated credential profile names.
HEADLESSCODE_OPENSHELL_CPU / HEADLESSCODE_OPENSHELL_MEMORY	2 / 4Gi	Per-sandbox resource requests.
HEADLESSCODE_OPENSHELL_NAME_PREFIX	hcls	Prefix for deterministic sandbox names.
HEADLESSCODE_OPENSHELL_SCRATCH_ROOT	~/.local/share/headlesscode/openshell-sessions	Host scratch directory that the gateway container must see at the same path.

The headlesscode openshell-session command provides a single-session live entry point; run headlesscode openshell-session --help for options.

Parallel work and GitHub intake

orchestrate runs a parallel round from GitHub issue numbers or a JSON file. It splits work, creates a worktree per group, starts workers, watches for completion, and reviews results. QA and deployment approval are optional.

headlesscode orchestrate --repo /path/to/repo --issue 42 --issue 43 --qa
headlesscode orchestrate status --repo /path/to/repo --wait --timeout-ms 7200000

watch polls GitHub for issues with a chosen label and starts bounded batches. It requires GH_TOKEN or GITHUB_TOKEN; it performs intake only. Use a later orchestrate run to monitor, review, QA, or deploy a batch.

GH_TOKEN=... headlesscode watch \
  --owner my-org --repo /path/to/repo --label needs-agent --run-once

Command	Important options	Behavior and limits
headlesscode orchestrate --repo <path>	Repeat --issue <n> or use --issues-json <file>; `--execution-provider local	openshell, --qa, --deploy, --no-review, --dry-run, --max-iterations , --max-rework-cycles , --max-continuations `
headlesscode orchestrate status --repo <path>	--wait, --timeout-ms <n>, --json	Reads durable round state; --wait blocks until terminal state or timeout.
headlesscode orchestrate stop --repo <path>	Repeat --group <name>	Stops selected groups' worker process trees.
headlesscode watch --owner <o> --repo <path> --label <name>	`--execution-provider local	openshell, --run-once, --dry-run, --max-per-sweep , --max-concurrent-sessions , --retry-failed`

Both orchestration and watcher enforce a shared concurrency cap, defaulting to 3 (HEADLESSCODE_MAX_CONCURRENT_SESSIONS). Orchestration aborts when the cap is full; the watcher leaves excess issues pending. The watcher records idempotency state under <repo>/.worktrees/.watcher-state.json by default. Use --help on a command for its complete options. Detailed guides: orchestration, issue watcher, QA implementation, and deployment gate.

Project registration and search

Registering a project detects its stack, ensures .gitignore excludes .headlesscode/, and builds a code-search index and codemap. Indexing calls an embedding API and can incur charges unless skipped or configured for Ollama.

headlesscode init --workspace ~/Projects/your-project
headlesscode init --workspace ~/Projects/your-project --skip-index

See headlesscode init --help for --skip-codemap and embedding-backend options. The CLI also provides index, codemap, project-store, GitHub App, and decision-proxy commands; run headlesscode --help for the command list and each subcommand's --help for complete usage.

Recursive self-improvement

headlesscode improve --dry-run resolves the base commit and prints planned candidate worktrees. A real run requires PostgreSQL, a shared S3-compatible artifact store, and at least one registered headlesscode rsi-worker. The coordinator queues sanitized mutation snapshots and visible evaluation jobs; workers run each in a fresh OpenShell guest. Fitness, paired baseline comparison, archives, and selection stay in the coordinator. Hidden evaluation remains disabled. A 2026-09-29 bounded run used two workers on the same local OpenShell gateway; both candidate evaluation jobs were leased concurrently. The run used a temporary clamp.js fixture and does not establish general headlesscode improvement or multi-gateway operation. An earlier bounded run passed visible checks but made no source change and was rejected.

npx tsx src/cli.ts improve --repo . --dry-run
npx tsx src/cli.ts improve --repo . --population 2 --generations 1

Before starting workers, build the standard and RSI guest images on each OpenShell gateway host that will run RSI jobs. Build the larger training image only on gateways whose workers will accept model-training or paired model-evaluation jobs:

docker build -f docker/OpenShell.Dockerfile -t headlesscode-openshell:local .
docker build -f docker/OpenShell-RSI.Dockerfile -t headlesscode-openshell-rsi:local .
docker build -f docker/OpenShell-RSI-Training.Dockerfile -t headlesscode-openshell-rsi-training:local .

The RSI Dockerfile extends headlesscode-openshell:local and removes the RSI source, test files, and hidden evaluation suite from the guest image. See the RSI design for worker and queue configuration.

The queue stores job state, worker registrations, leases, retries, and admission policy in PostgreSQL; artifact bytes remain in object storage. Local integration tests used 12 simulated workers and 100 queued jobs, including a 20 MiB artifact. Each worker process currently runs one guest at a time and must be configured with a unique worker ID and OpenShell gateway ID. The two-worker run observed 4.008 seconds of concurrent evaluation leases on one gateway. A local PostgreSQL/ RustFS test drained the remaining 96 jobs with 12 simulated workers in 446 ms (215.2 jobs/s), after the initial four jobs were claimed and completed to verify admission limits; claims still serialize on a queue-policy row, and neither result qualifies a multi-host deployment. Remaining work is:

Issue	Work
#3	OpenShell candidate isolation is implemented; live multi-gateway qualification remains.
#4	Content-addressed artifacts are implemented; signed evaluator provenance and hidden evaluation remain.
#5	PostgreSQL queue, leases, retries, admission, and configured workers are implemented; live fleet qualification remains.
#6	Bounded adaptive independent search supports an initial population plus one evidence-driven follow-up; repeated stages remain out of scope.
#7	Fixture-backed curriculum replay and explicit promotion are implemented; wording-to-capability measurement remains unproven.
#8	Adversarial review and bounded OpenShell break tests are implemented; live provider-backed review is unvalidated.
#9	An OpenShell QLoRA prototype is covered by mocked job tests; the supplied GGUF is rejected before enqueue, and no live training is validated.

See the RSI design and run progress.

Core CLI options

Option	Default or source	Purpose
--task <text> / --task-file <path>	One is required unless --dry-run	Task prompt; task file is resolved relative to the workspace.
--workspace <path>	HEADLESSCODE_WORKSPACE_ROOT or current directory	Repository directory exposed to the worker.
--mode <slug>	code	Built-in or project .roomodes mode.
--model <id>	OPENROUTER_MODEL or deepseek/deepseek-v4-flash-0731	Model ID.
--max-iterations <n>	250 for direct CLI sessions; orchestrator workers default to 50	Per-session loop bound.
--consecutive-error-limit <n>	3 (local code backend may use 6)	Consecutive tool/model errors before stopping.
--max-cost-usd <n> / --max-duration-ms <n>	HEADLESSCODE_MAX_COST_USD / HEADLESSCODE_MAX_DURATION_MS; disabled if unset	Per-session budget caps. A tripped cap aborts the session.
--memory-dir <path> / --no-memory	Off unless HEADLESSCODE_MEMORY_DIR or option is set	Enable project facts and rolling session summaries, or explicitly disable.
--allowed-commands <list> / --denied-commands <list>	CLI, environment, .headlesscode/permissions.json; allow list is empty by default	Command-prefix policy. Denials win; dangerous shell substitutions are blocked. See SECURITY.md.
--protected-files <globs> / --allow-protected-writes	.env,.env.*,*.pem,*.key,id_rsa*	Block writes matching protected files; explicit escape hatch.
--dry-run	Off	Build prompt and validate configuration without a model call or API key.
--log-file <path>	No file	Also append structured session logs to a file.

Run headlesscode --help for advanced controls such as context condensation, checkpoints, recursive delegation, session pause, and LLM timeout. Some options are backend-specific; help output and source defaults are authoritative.

Architecture

The core loop builds the project-specific prompt, calls the configured model, executes the selected mode's available tools, and repeats until completion or a configured limit. File tools are confined to the workspace path; shell commands run with the process user's privileges unless an external boundary such as OpenShell is configured. Mode instructions and safety controls are distinct: prompt instructions guide the model, while filesystem or command restrictions must be enforced by the runtime or sandbox.

Area	Entry points	Responsibility
CLI and session loop	src/cli.ts, src/engine/	Command dispatch, prompt construction, LLM/tool loop, iteration and context limits.
Model and tools	src/llm/, src/tools/	OpenRouter client, tool execution, output handling, and workspace path checks.
Parallel orchestration	src/orchestrator/, scripts/spawn-parallel-worktrees.sh	Issue grouping, worktree workers, completion state, review, rework, QA, and deploy gating.
GitHub intake	src/watcher/	Label polling, durable idempotency, pending work, and bounded spawning.
Runtime providers	src/cloud/	Local process, Docker, and OpenShell implementations of the session lifecycle. orchestrate and watch can select OpenShell for worker sessions.
Memory and budgets	src/memory/, src/budget/	Opt-in project memory, cost/time budgets, and session concurrency accounting.
QA and deploy gate	src/qa/, src/deploy/	Read-only QA verdicts and explicit human approval before deployment.
Project map and search	src/codemap/, src/codesearch/	Deterministic module maps and repository search indexes.

The model only receives tools supported by the selected mode and executable runtime. Unsupported vendored tool schemas are not advertised. This keeps the model's action set aligned with the current executor; it does not make arbitrary shell commands safe by itself.

Development

Command	Purpose
npm install	Install dependencies.
npm run typecheck	TypeScript type check.
npm run smoke	Vendored prompt-builder smoke test; no network.
npm test	Unit tests using local/fake dependencies where provided.
npm run cli -- --dry-run --workspace .	Build this repository's system prompt.
bash scripts/e2e/run.sh	Phase 1 CLI integration against mock OpenRouter.
bash scripts/e2e-phase2/run.sh	Orchestrator spawn/watch/review integration.
bash scripts/e2e-phase4/run.sh	QA and deploy-gate integration with fake deploy.
bash scripts/e2e-phase5/run.sh	Watcher integration against fake GitHub and stubbed spawner.
bash scripts/e2e-phase6/run.sh	Budget-abort and concurrency-cap integration.

Unit tests can inject a fake LLM client into HeadlessSession; the listed end-to-end scripts use local mock services. OpenShell provider tests use a fake CLI. A live OpenShell 0.1.2 run called DeepSeek V4 Flash through OpenRouter, imported its Git result, and denied a host-worktree canary write. The earlier shared-worktree mount was removed after a live probe showed it exposed host Git and control files. See the OpenShell guide for the current clone-and-import boundary and its validation.

Implementation status

Area	Status	Details
Runtime engine	Implemented	Portable Zoo Code core, model client, tool executor, parser, CLI, and tests.
Orchestration	Implemented	Parallel worktrees, issue splitting, status tracking, review, and recovery. See guide.
Memory	Implemented	Opt-in per-project facts and session summaries with a local store; remote store remains a stub.
QA and deploy approval	Implemented	Read-only QA plus a fail-closed human-approval deploy gate. See orchestration guide and deploy gate.
GitHub watcher	Implemented	Poll-based label intake; webhook server is not implemented. See guide.
Budget and concurrency controls	Implemented	Per-session limits and a cross-process concurrency cap.
Local process provider	Implemented	Existing host-process worker path behind the provider lifecycle interface.
Docker provider	Implemented	Container-backed provider implementation; orchestrate does not currently select it.
OpenShell provider	Implemented	Disposable clone, separate scratch data, validated Git bundle import, and sandbox teardown. See guide.
Context management	Implemented	Token-aware condensation summarizes older turns; message-count truncation remains the non-fatal fallback. See src/engine/condense.ts.

Attribution

This project contains Apache-2.0-licensed code derived from Zoo Code (Zoo-Code-Org/Zoo-Code, commit ca9b60f), itself a Roo Code fork. Prompt text, tool schemas, and mode/rules loading logic are reused under the terms of the Apache License 2.0. See LICENSE and ATTRIBUTION.md.