Docs / Quickstart

Quickstart

Local daemon + CLI in under 60 seconds.

Codencer runs locally. A few commands get you to a green proof on Linux, WSL2, or macOS. The path that follows assumes Go, git, and a working make on your PATH. If you don't have them, install them first — Codencer is a Go binary with a CGO SQLite driver and no other runtime dependencies.

Prerequisites

  • Go 1.25.0+ — the daemon, CLI, connector, relay, MCP SDK proof helper, and cloud control plane are all Go binaries.
  • Git — required for worktree isolation; every attempt runs in its own worktree off your repo.
  • A C compiler (gcc or cc) — required for the CGO-based SQLite driver.
  • curl — for health checking and polling helpers.
  • jq or Python 3 — recommended for shell automation wrappers that parse Codencer's JSON output.

Operating systems: Linux native, WSL2 (Ubuntu/Debian), and macOS are supported. Native Windows is not a supported daemon platform — use the Antigravity Broker (agent-broker) for cross-side communication; see the Self-hosting chapter.

Clone and build

git clone https://github.com/lookmanrays/codencer
cd codencer

make setup            # initialize environment, check requirements
make build-supported  # build the supported beta-track binaries

If you only need the local and relay tracks, make build is sufficient. If you need the Windows-side broker (Antigravity), add make build-broker.

Verify the environment:

./bin/orchestratorctl doctor

doctor checks every prerequisite and reports green or red on each. If anything is red, fix it before continuing. The runtime-readiness diagnostic is /api/v1/compatibility — useful for checking binary availability, simulation mode, and local bindings.

First proof

The simplest proof is the local v1 smoke test. It opens a run, registers a step, dispatches it through the simulation adapter, and verifies the structured result lands.

./scripts/smoke_test_v1.sh
make smoke

A few minutes, two commands, green or red. If both are green, your local install is verified at the canonical local proof level.

What just happened

smoke_test_v1.sh exercised the daemon in simulation mode — no real LLM credits consumed, no real coding agent invoked. It opened a run, registered a single step, and dispatched it through a simulated adapter. The adapter returned a structured artifact. A validation ran. A gate evaluated. The result landed in SQLite.

make smoke then ran the wider local suite — the canonical local proof per the repo's beta testing guide.

What's deferred from the canonical local proof

NOTE — friction: The canonical local proof is simulation-first at the v0.2.0-beta tag. The codex adapter has fake-binary codex exec coverage and stricter live-smoke checks, but live authenticated Codex service calls remain operator-environment proof. Treat /api/v1/compatibility and orchestratorctl instance --json as runtime truth for local readiness.

For live executor proof beyond simulation, run:

make flagship-planner-smoke

# or with a live Codex binary on your PATH:
FLAGSHIP_LIVE_CODEX=1 CODEX_BINARY=codex make flagship-planner-smoke

Next steps

The repo's BETA_TESTING.md is the next page in your sequence. It documents the five public beta tracks:

  • Local-only daemon + CLI — what you just ran. make smoke.
  • Self-host relay + runtime connector — PLANNER_TOKEN=<planner-token> make self-host-smoke-mcp. See Self-hosting.
  • Self-host cloud control plane — make build-cloud && make cloud-smoke. Multi-tenant control plane.
  • Planner / client integrations — ChatGPT custom MCP, Claude Code remote MCP, Anthropic Messages API. Operator-loop proof, not universal product compatibility.
  • Provider connectors — Slack strongest, Jira polling-first, others narrower.

Each track has its own proof command and its own boundary line in BETA_TESTING.md. The boundary line is honest about what's verified and what's compatibility-only.

When the smoke test fails

Three common categories:

  1. Missing prerequisite. doctor will tell you which one. Fix it and re-run.
  2. Stale binary. Run make clean && make build-supported. Rebuild from a clean tree.
  3. Local state drift. Inspect via orchestratorctl instance --json and the daemon's /api/v1/compatibility endpoint before resetting anything.

If the failure isn't in those three: open an issue with the doctor output, the make target you ran, and the last 50 lines of orchestratord log. The repo's TROUBLESHOOTING.md is the deeper reference.

Quickstart · Codencer