singular

singular command [args]

singular is the command-line launcher for Singular, a bash and Python orchestration engine that runs autonomous AI coding agents in parallel against a Git repository. The binary you type is singular; the upstream checkout is singular-lite. It is not related to Singularity/Apptainer containers.The engine is installed once per machine (`bash install.sh` from a checkout) into `SINGULARHOME` (default `~/.singular`): versioned trees under `versions/<ver>/`, a `current` symlink, and `bin/singular`. Each consumer repo pins the engine in `.singular-version` (overrides `engineVersion` in `singular.config.json`). The launcher resolves that pin, binds `SINGULARROOT` to the repo, and execs the matching engine scripts.Scheduling is three-tier. L0 is the single origin loop (`reconcile`): import planner proposals, recover expired leases, integrate finished branches, dispatch work, snapshot. L1 planners produce batches of tasks per DAG area. L2 workers run one task in an isolated `git worktree` on a per-task branch and write a state packet. A configured gate command (for example a test suite) runs after the worker; an auditor model reviews the packet; a decider maps `(failure-class, retries-left)` to retry, amend-scope, escalate, or park.Detached dispatch is on by default (`SINGULARDETACHEDDISPATCH=1`): `reconcile` pre-leases frontier tasks, spawns workers in their own session, and returns in seconds. A reaper attributes completions on later cycles. Set the variable to `0` for the older synchronous batch wait.Prerequisites: Bash >= 4, python3, git, and at least one configured runner CLI on `PATH` (`claude`, `codex`, or another runner named in config). On macOS the system `/bin/bash` is 3.2; install a newer bash and optionally set `SINGULARBASHBIN` to its absolute path. The launcher is licensed GPL-3.0.

setup [--json] [--no-test] [--test-async]

One idempotent path from an ordinary Git repo to a verified, STOPPED consumer. Resolves the engine pin, installs a matching local checkout if needed, writes `.singular-state/STOP` first, scaffolds, migrates, runs doctor, and optionally records a regression run. Never actuates.

Scaffold `singular.config.json`, `docs/orchestration/`, and `.singular-version` in the current repo.

Structured preflight. JSON checks have stable `id`, `severity`, `requiredFor`, and `remediation`.

L0 reconciler: import staged planner tasks, recover stale leases, integrate finished branches, dispatch frontier workers, snapshot. --actuate performs the cycle. --drain waits for detached workers.

Self-driving autonomy loop. Honors `SINGULARMAXHOURS` (default 12).

Run one task through L1 planning, L2 worker, gate, and audit.

Orchestration status (same as `reconcile --status`).

Merge accepted worker branches into the target branch.

Cooperative halt, restart, and nap/backoff reset.

Owner- and artifact-hash-bound human approval records (schema v2 preferred path).

Report every contract violation in a gate-result file.

Supervised engine regression suite. Requires an engine checkout (installed copies under `~/.singular/versions/` do not ship tests). Evidence lands in the current repo under `.singular-state/test-runs/`.

Pin this repo in `.singular-version`. With no argument, pins the machine `current` version.

Raise `schemaVersion` in `singular.config.json` through the engine's `migrations/` chain.

Print CLI version and the resolved engine home.

Local visualization server (default `http://127.0.0.1:8765`). URL persisted at `.singular-state/console.url`.

Read-only context metrics from the event log.

Cap run history, prune integrated worktrees, rotate events.

Print the launcher usage. `graph` and `experiment-report` appear only when `SINGULARCTXGRAPH=1` or `SINGULARCTXEXPERIMENT=1`.

singular.config.json

Per-repo declarative config: `targetBranch`, `gateCommand`, `runner`, `areas`, `promoter`, `worktreeCopyPaths`, `modules`, capability/role profiles, evidence limits, bootstrap commands, and `legacyCompatibility`. The starter `gateCommand` is `false` so a new repo fails closed until you set a real health check.

Optional shell extras (computed values, functions).

Gitignored operator overrides and secrets.

Authoritative engine pin for this repo.

Machine install root (default `~/.singular`). Must be an absolute path.

Override the resolved engine tree (required to run `singular test` against a checkout).

Absolute paths to Bash >= 4 and a specific Codex binary. `SINGULARBASHBIN` is bootstrap-only and is ignored inside `singular.config.json`.

Worker slots, tasks per reconcile cycle, and autonomy wall-clock budget.

Detached workers, automatic merge of accepted branches, and whether to push. Direct commands default `SINGULAR_PUSH=0`; `singular auto` defaults to `1`.

Integration branch. Required for actuate cycles (also settable in JSON).

Opt-in flags that expose `singular graph` and `singular experiment-report`.

Not singularity(1) (containers). macOS users must install Bash >= 4 or the launcher exits `SINGULARBASHUNSUPPORTED`. `singular test` refuses installed (non-checkout) engine trees. `setup` installs a missing pin only from a matching engine checkout already on the machine — there is no download step. The default promoter only knows its built-in node registry; a custom DAG that omits `promoter` stalls after layer 0 with `promotion: no promotable frontier gates`. Singular executes repo-configured shell commands and launches coding agents in worktrees — review config and task files before running it in an untrusted repo. Schema v2 rejects unbound `accept-waiver` / `promote-gate --operator` paths unless `legacyCompatibility.unboundWaivers` is `true`.

Singular is developed by alex-reysa in the singular-lite repository (GPL-3.0). The machine launcher is a Bash script (`cli/singular`) that resolves a pinned engine version and execs `engine/*.sh`. Engine releases are identified by the repo `VERSION` file (0.19.x line at documentation time); the embedded CLI version string is independent.

claude(1), codex(1), aider(1), git(1), git-worktree(1)

Source code