Codencer is a persistent orchestration daemon designed to securely manage, execute, validate, and audit coding tasks performed by external agents. It acts as the system of record between a high-level Planner (human or LLM) and tactical Coding Agents (Codex, Claude-code, Aider). It is designed for local-first, self-hosted developer toolchains.
Important
Project Status: Public Beta (v0.1.0-beta). Codencer is technically functional for local dev use, with a hardened execution path via the Codex adapter. While the core engine is stable, the API and protocols are subject to refinement as we gather community feedback.
Execution Path Note: Codencer depends on Git Worktrees for isolating task attempts. Therefore, cloning the repository via
git cloneis the only supported execution path. Downloading a ZIP source archive will fail during targeted execution.
Codencer is a bridge, not a brain. It does not decide the high-level strategy; it executes tactical instructions and reports high-fidelity evidence.
[ Planner (Brain) ] <---------- (ResultSpec) ---------+
| |
(TaskSpec) [ Bridge (Codencer) ]
| |
+-------------------> [ Agent (Worker) ] <-----+
(File Edits)
- Planner: You, a Chat UI, or an agentic planner. Decides what to do.
- Bridge (Codencer): Receives the
TaskSpec, manages workspace isolation (Git Worktrees), enforces policies, and monitors execution. - Coding Agent: The underlying tactical tool performing the actual work (e.g.,
codex-agent,claude-code).
For the definitive Day-0 guide, see the Canonical Local Runbook.
Get up and running in simulation mode to verify the orchestrator logic.
# Initialize and build binaries
make setup build
# (Optional) Verify your local environment
./bin/orchestratorctl doctorChoose your execution tier in .env (Simulation is enabled by default in .env.example):
# Start in Simulation Mode (Background)
make start-sim
# OR Start in Real Mode (Requires agent binaries like codex-agent)
# Edit .env: ALL_ADAPTERS_SIMULATION_MODE=0
make startSubmit a task and wait for the bridge to report results. For the full auditing sequence, see the Canonical Local Runbook.
# 1. Start a new mission (System of Record)
./bin/orchestratorctl run start first-run my-project
# 2. Submit a tactical task and wait for completion
./bin/orchestratorctl submit first-run examples/tasks/bug_fix.yaml --wait
# 3. View the Authoritative Truth (The Summary)
# Note: Use the Step UUID Handle printed after submission
./bin/orchestratorctl step result <UUID>Codencer ensures that every tactical execution is backed by high-fidelity evidence. Follow the Canonical Sequence in EXAMPLES.md to audit your task:
- Authoritative Summary:
step result <UUID>(Start here). - Raw Execution Trail:
step logs <UUID>(The agent's brain). - Audit Evidence:
step artifacts <UUID>andstep validations <UUID>(The proof).
completed: Goal met, all tests passed.completed_with_warnings: Success, but with non-critical issues (lint/tests).failed_terminal: Goal not met (e.g. tests failed). Review validations.timeout: Execution exceeded limits. Review logs for hangs.cancelled: Manually stopped by the operator.needs_approval: Policy gate hit; awaiting operator intervention.needs_manual_attention: System ambiguity or crash. Review daemon/agent logs.
Every task execution leaves a permanent audit trail:
- Summary: Run
./bin/orchestratorctl step result <id>for the high-level spec. - Logs: Run
./bin/orchestratorctl step logs <id>for the raw agent stdout. - Artifacts: Every modified file and diff is stored in
.codencer/artifacts/. Use./bin/orchestratorctl step artifacts <id>to see the exact paths and SHA-256 hashes. - Validations: Run
./bin/orchestratorctl step validations <id>to see specific test/lint results.
For a deeper dive into agent installation and advanced configuration, see the Environmental Reference Guide.
Agent-driven coding is non-deterministic. Codencer provides the guardrails:
- Workspace Safety: Agents run in isolated Git Worktrees. Diffs are captured and validated before any commit.
- Audit-Proof Ledger: Every attempt is recorded in a local SQLite database (embedded via CGO) with SHA-256 hashes of all artifacts.
- Idempotency: Interrupted tasks can be resumed or securely analyzed post-crash.
- Validation-First: Tasks only "complete" when your defined validation commands (tests, linters) pass.
As a local-first Beta/MVP, Codencer has the following constraints:
- Relay Only: The bridge does not "think" or plan; it only executes what the Planner instructs.
- Single-User: Designed for local development; no multi-user or cloud concurrency.
- Static Extension Routing: The experimental VS Code extension assumes the daemon binds at
127.0.0.1:8085. Dynamic connection configuration for running instances on multiple ports is not yet natively surfaced in the IDE client. - Agent Dependency: "Real Mode" efficacy is strictly bound to the quality of the underlying agent (Codex, Claude, etc.).
- Manual Decisions: The bridge reports terminal states; all recovery or retry decisions remain with the human operator or external planner.
Codencer is currently in an MVP/Beta state. Use the following matrix to understand current support:
| Feature Area | Status | Description |
|---|---|---|
| Orchestration Core | ✅ Ready (Beta) | Persistent SQLite ledger, state machine, and Git Worktrees. |
| CLI & MCP Layer | ✅ Ready (Beta) | Structured JSON outputs, log tailing, and health checks. |
| Codex Adapter | ✅ Ready (Beta) | High-fidelity relay for the codex-agent binary. |
| Instance Identity | ✅ Ready (Beta) | One-repo-one-daemon model with explicit instance inspection. |
| Run Metadata | ✅ Ready (Beta) | Label runs by project, conversation, planner, and executor. |
| Claude/Qwen Adapters | 🟡 Functional | Basic subprocess wrappers; lacks deep artifact extraction. |
| Simulation Mode | ✅ Ready (Beta) | Robust stubs for orchestrator validation without LLM use. |
| Diagnostics & Health | ✅ Ready (Beta) | CLI-based doctor and smoke verification tools. |
| IDE Chat Bridge | 🧪 Prototype | Experimental proxy-mediated file access via VS Code. |
| Cloud / Multi-User | 🚫 Non-Goal | Codencer is strictly local-first and self-hosted. |
Codencer distinguishes between different failure modes to help you recover faster:
| State | Meaning | Typical Recovery |
|---|---|---|
completed |
Success: All goals and validations met. | Next step. |
failed_validation |
Validations failed: Agent finished but tests/lint failed. | Fix code/prompt. |
failed_adapter |
Agent crashed: The binary or process failed. | Check config/keys. |
failed_bridge |
Bridge error: Orchestrator infrastructure failure. | Check disk/git/locks. |
timeout |
Time limit exceeded: Process was killed. | Increase timeout. |
cancelled |
Explicit stop: Operator aborted the run. | Resubmit if needed. |
- Simulation Mode (
make start-sim): Only validates the Orchestrator. It tests if the ledger, state machine, and CLI are working. It does not test if the agent can actually code. - Real Mode: Tests the full end-to-end loop with real agents. Codex-agent is the primary supported path; others are in early beta.
Review the following guides to get started with Codencer.
- Canonical Local Runbook — The definitive Day-0 operator flow.
- Environmental Reference — Prerequisites, configuration, and agent setup.
- Troubleshooting — How to handle non-success states and recovery.
- Architecture Overview — High-level design and the "Bridge not Brain" model.
- Gap Audit & Roadmap — Current V1 release blockers and debt.
- Development Progress — Historical and current technical timeline.
- Technical Task Backlog — Detailed micro-task status for maintainers.
- Contributing Guide — How to set up a dev environment and submit PRs.
Codencer is designed around a strictly local, repo-bound execution model:
- 1 Git Clone = 1 Daemon Instance: Each repository checkout manages its own ledger and workspaces.
- Multi-Instance Support: To run multiple instances on the same machine, simply use different ports (e.g.,
PORT=8086 make start). - Identity Verification: Use
./bin/orchestratorctl instanceto verify which repository and port a daemon is serving.
For more details, see Setup & Multi-Instance Workflows.
Codencer is released under the MIT License. See the LICENSE file for the full text.