Install

Install from the published wheel — never from the git repo

cortexbuild-core is not on PyPI. It is published as a wheel to the CortexBuild distribution index on every release tag. Always install from that index. Installing from a git URL is not supported: it builds an unreviewed working tree, skips the tag/version verification the release pipeline enforces, and needs credentials for a private repository.

Prerequisites

Requirement	Notes
Python 3.11+	Declared minimum is >=3.11.
git	Needed for repo analysis (git-log mining) and git-URL onboarding.

Install

pip install --upgrade cortexbuild-core \
  --find-links https://cortexbuilddist40b9jc.blob.core.windows.net/dist/index.html

The index is a flat PEP-style find-links page listing every published wheel, so pip resolves the newest release automatically. Pin explicitly when you need a specific version:

pip install "cortexbuild-core==0.2.4" \
  --find-links https://cortexbuilddist40b9jc.blob.core.windows.net/dist/index.html

Extras are appended to the requirement as usual, e.g. "cortexbuild-core[graph,mcp]".

Dev install (contributors only)

If you are changing CortexBuild itself, clone the repo and install editable from the repository root:

pip install -e ".[graph,postgres,redis]" --group dev

• The [graph] extra adds tree-sitter parsers for JavaScript, TypeScript, and Go. Python is analysed out of the box — Pass-2 graph extraction for Python uses the standard-library ast module and needs no extra. Without [graph], non-Python codebases still get the structural and debt passes.
• [postgres] and [redis] are optional memory backends; drop them if you don't need persistence.
• --group dev pulls in the development toolchain.

Optional extras

A few more extras unlock specific, opt-in capabilities:

• [gemini] — native Google Gemini adapter (google-genai), in addition to the native Anthropic adapter and the built-in OpenAI-compatible adapter (any base_url). (No native AWS Bedrock or Google Vertex adapter ships today; those clouds are reachable through an OpenAI-compatible gateway — CortexBuild ships no native Bedrock/Vertex adapter.)
• [server] — opt-in HTTP transport over the task/execution seam. It writes a task single-source-of-truth under .cortexbuild/tasks/; it does not run agents in-process.
• [ide] — read-only file-reader over .cortexbuild/ for IDE surfaces.
• [mcp] — read-only MCP server so an IDE/agent host (Claude, VS Code, Cursor, Codex) can consult CortexBuild over the standard protocol. Pulls no third-party dependency. See MCP & A2A integration.
• [a2a] — read-only A2A Agent Card discovery surface (the agent↔agent complement to [mcp]). See the same guide.

Two analysis/insights commands are also worth knowing early — eval (offline, no-LLM, deterministic conformance scoring) and remediation (advisory, reversible, applied only under an explicit --approve gate, never auto-merged). See the CLI Reference for the full command set.

Verify the install

Confirm the CLI is on your path and reports a version:

cortexbuild version

cortexbuild info

version prints the package/framework version; info prints environment and capability details. If both run without error, you're ready to onboard a repo.

License-gated usage

Operational commands are license-gated for registered usage.

Local activation:

cortexbuild auth activate --key cbk_<org>_<expiryYYYYMMDD>_<plan>

CI/non-interactive usage:

set CORTEXBUILD_LICENSE_TOKEN=cbk_<org>_<expiryYYYYMMDD>_<plan>

Status and removal:

cortexbuild auth status --json
cortexbuild auth logout

For tests or emergency local development only, CORTEXBUILD_LICENSE_BYPASS=1 skips the gate.

Which mode am I using?

CortexBuild has two operating modes. Understanding which one applies to you determines whether you need an LLM API key:

Mode	When it applies	LLM key needed?
Rendered-into-host	You ran cortexbuild render and use the generated files inside Copilot, Claude Code, Codex CLI, or Cursor	No — the host tool supplies model access
Own orchestration engine	You invoke CortexBuild's orchestrator directly (e.g. cortexbuild run, CI automation) with CORTEXBUILD_LLM=1	Yes — configure .cortexbuild/llm-config.yaml with your endpoint and set the key as an environment variable

I use GitHub Copilot in VS Code

No API key needed. Run cortexbuild render to write rules and agent personas into .github/copilot-instructions.md and .github/agents/. Copilot picks up the rendered instructions automatically and uses its own models.

I want CortexBuild to call an LLM directly

Set CORTEXBUILD_LLM=1 and create .cortexbuild/llm-config.yaml:

# Example: local Ollama (zero-egress, no consent needed)
base_url: "http://localhost:11434"
model: "llama3:8b"
locality: "local"
provider: "openai"   # Ollama speaks the OpenAI protocol

# Example: Anthropic Claude (cloud, full consent gate)
provider: "anthropic"
model: "claude-opus-4.7"
api_key_env: "ANTHROPIC_API_KEY"   # env var NAME, never the key value inline
locality: "cloud"

See Provider Adapter for all provider options and the full locality-gate reference.

Per-agent model tiers (own orchestration mode only)

When CORTEXBUILD_LLM=1 is active, CortexBuild's router assigns each agent to a model tier:

Tier	Agents	Why
reasoning_heavy	Planner, Critic, Security Compliance, PR Reviewer	Deep reasoning; these agents produce or gate high-consequence output
balanced	Builder, Tester Validator, Optimizer, Enterprise Orchestrator	Cost-quality balance; handle the bulk of task volume
fast_cheap	Explore	Read-only summarisation; latency and cost matter most

You can override per agent in .cortexbuild/llm-config.yaml by adding an agent_overrides block:

agent_overrides:
  builder:
    model: "claude-opus-4.7"   # override Builder to reasoning_heavy if needed

Edge cases: - Host-tool rendered mode — Tier routing does not apply. The host vendor (Copilot, Claude Code, Cursor) controls which model runs each agent. There is no per-agent model switching. - No eligible model available — If a requested tier has no configured model, CortexBuild fails closed: the task is paused and the user is notified. It will not silently fall back to a lower-tier model for a reasoning_heavy task (e.g., plan review or Critic gate) because a capability downgrade on a security-sensitive gate must be explicit. - Cross-model Critic — For medium+ risk tasks, the Critic automatically runs on a different model than the Planner to avoid reviewing its own blind spots. The orchestrator records independent_reviewer: <model> in the task output.

Next

→ Onboard Your Repo — the step-by-step walkthrough.