Skip to content

How it works

This page explains the mechanism: what runs where, what CortexBuild reads and writes on your machine, how rules become instructions your AI tools follow, and how the governed review workflow fits together. For what leaves your machine and how your credentials are handled, see Security & privacy.

The pieces

Four things make up a CortexBuild install:

  • The CLI, installed on your machine (or CI runner) from the published wheel index.
  • Your AI coding tools — Copilot, Claude Code, Codex CLI, Cursor — which read the files CortexBuild renders and do the actual work of writing code.
  • Your model provider, if you choose to run CortexBuild's own orchestrator directly (CORTEXBUILD_LLM=1). Bring your own key; CortexBuild never supplies model access itself.
  • CortexBuild's own services, reached only at their canonical hosts: license.cortexbuild.dev for licensing and telemetry, dist.cortexbuild.dev for the package index, and admin.cortexbuild.dev for the admin portal.
flowchart LR
    cli["CortexBuild CLI\n(your machine)"]
    tools["Your AI tools\n(Copilot / Claude Code / Codex / Cursor)"]
    provider["Your model provider\n(BYO keys, optional)"]
    license["license.cortexbuild.dev\n(licensing + telemetry)"]
    dist["dist.cortexbuild.dev\n(package index)"]
    admin["admin.cortexbuild.dev\n(admin portal)"]

    cli -->|renders rules into| tools
    cli -.->|"opt-in orchestration"| provider
    cli -->|activate / refresh / telemetry| license
    cli -->|install / upgrade| dist
    admin -->|issues licences, reads usage| license

Onboarding: reading your repository

cortexbuild init run (or the onboard wizard) analyses your repository in passes and writes what it finds under .cortexbuild/ — nothing leaves your machine during this step:

  1. A structural pass maps the codebase: languages, frameworks, module boundaries.
  2. A convention pass mines your git history and existing code for the rules your team already follows but never wrote down.
  3. A debt/risk pass flags recurring failure patterns worth guarding against.
  4. The results are written to .cortexbuild/analysis/ and proposed as rules for you to review before anything is rendered into your AI tools.

Render: rules become instructions

cortexbuild render takes the rules single-source-of-truth and writes it out per tool: .github/copilot-instructions.md and .github/agents/*.agent.md for Copilot, CLAUDE.md and .claude/agents/*.md for Claude Code, AGENTS.md for Codex CLI, and .cursor/rules/*.mdc for Cursor. Every rendered file is fully CortexBuild-owned — a hand-edit to a rendered file does not survive the next render; durable changes go in the rule source or your org standards pack.

Beyond the rendered files, render also wires up executable hooks for hosts that support them: session-start build checks, turn-end telemetry, and an edit guard for paths you mark off-limits. See Executable hooks for the per-host coverage table.

The governed workflow

CortexBuild renders a fixed, auditable sequence of specialised review roles — Planner → Critic → Builder → Tester → Security → Optimizer → PR Reviewer — into the AI tools you already use. CortexBuild renders and governs the workflow; your host AI tools execute it. That distinction matters: these roles flag and gate, they do not merge anything by themselves — your existing approvals decide what actually lands. See Adopt your own governance for how to wire this into a repo that already has its own conventions.

The learning loop

Defects and their fixes are recorded in a recurrence ledger (.cortexbuild/recurrence-ledger.yaml) so the same class of failure is caught earlier the next time an agent touches similar code. Deterministic checks — conformance scoring, the offline eval harness, render --check — back this up with checks that flag a change the same way regardless of which model produced it. See Conformance score and ROI & insights report.

Models and your keys

Most of the pipeline runs with no model at all — rendering, conformance scoring, and the recurrence ledger are deterministic. An LLM is only involved when:

  • your AI tool (Copilot, Claude Code, Codex CLI, Cursor) executes the rendered workflow using its own model access, or
  • you explicitly opt in to CortexBuild's own orchestrator with CORTEXBUILD_LLM=1 and a .cortexbuild/llm-config.yaml you provide.

In the second case you bring your own key, and you choose the provider: a local endpoint (Ollama, LM Studio, a self-hosted vLLM) for zero-egress operation, or a cloud provider through the built-in OpenAI-compatible adapter or a native adapter. See Configure your model for the full setup and the per-agent model-tier routing table.

Licensing

Every operational command requires a valid, Ed25519-signed licence, verified offline against an embedded public key — a licence cannot be forged by guessing a string. A licence belongs to a person: you activate it once in each repository checkout you work in, and each machine you use takes one device seat. The signed lease renews automatically online (cortexbuild auth refresh to renew explicitly, e.g. before a long offline stretch). See Install options & licensing and Set up in your repository for the full activation and renewal flow.

Next