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 <n>, --max-rework-cycles <n>, --max-continuations <n> | Worktree per group; default review is enabled. OpenShell applies to worker, plan-first, continuation, reviewer, QA, and rework sessions. --deploy uses the human-approval gate. | | 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 <n>, --max-concurrent-sessions <n>, --retry-failed | Label-based intake. --dry-run still needs a GitHub token to list issues, but writes no state and starts no workers. |

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.