cortex-ia

README

English | Español

---

⚡ What is Cortex-IA?

Cortex-IA is the enterprise-grade, deterministic Multi-Agent Control Plane & Orchestration Engine designed for autonomous software development with OpenCode.

Built as a single portable Go binary, Cortex-IA solves the fundamental challenges of multi-agent coding: race conditions, conflicting file edits, hallucinated task readiness, unmonitored background tasks, and unstructured coordination.

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                                   CORTEX-IA ECOSYSTEM                                       │
│                                                                                             │
│  ┌──────────────────────────┐   ┌─────────────────────────────┐   ┌─────────────────────────┐  │
│  │     OpenCode Agents      │   │   CORTEX-IA Control Plane   │   │  Cortex-IA Web Console  │  │
│  │ (Orchestrator, Discovery,│──▶│  (SQLite ACID DAG, Leases,  │──▶│  (Loopback SSE Kanban,  │  │
│  │  Investigate, Planner,   │   │   CAS Revisions, OpenSpec)  │   │   Audit Log & Intake)   │  │
│  │   Implement, Reviewer)   │   │                             │   │                         │  │
│  └──────────────────────────┘   └─────────────────────────────┘   └─────────────────────────┘  │
│                                             │                                                │
│                                             ▼                                                │
│                               ┌───────────────────────────┐                                  │
│                               │     CORTEX Server (MCP)   │                                  │
│                               │  (AST Graph & Blast Tree) │                                  │
│                               │  (Epistemic Evidence DB)  │                                  │
│                               └───────────────────────────┘                                  │
└─────────────────────────────────────────────────────────────────────────────────────────────┘

---

🌟 Key Superpowers

• 🔒 Zero-Race Concurrency with Exclusive File Leases (work lease)
  Prevents agents from overwriting each other's code. Agents must atomically reserve exclusive workspace-relative file paths with TTL leases before editing. Parallel native implementers safely share the workspace via disjoint file reservations (cortex_ia_file_reserve).
• 🎯 Deterministic Task DAG with Optimistic CAS Locking (work claim / transition)
  Tasks transition through strict state machines (backlog ➔ ready ➔ in_progress ➔ in_review ➔ done). Downstream dependencies automatically unlock only when prior dependencies receive an independent review approval.
• 🛡️ Tiered Review Gates (work approve)
  Implementers cannot self-approve. High-risk changes (concurrency, schema migrations, public APIs, auth/crypto, or wide churn) require an independent reviewer agent; data, documentation, configuration, and low-risk unitary changes use orchestrator auto-approval. The tier is an escalate-only floor: it may be raised with a stated reason but never lowered.
• 🧹 Zero Raw JSON Chat Hygiene & Typed Tool Authority
  Eliminates token bloat and hallucinated text parsing. Structured receipts are passed directly via typed tool calls (cortex_ia_work_transition and cortex_ia_work_approve) stored atomically in SQLite, while chat displays clean, readable Markdown summaries.
• 📐 Native OpenSpec SDD Integration (cortex-ia openspec)
  Built-in support for Specification-Driven Development with RFC 2119 delta specifications and a tiered workload policy (strict / flexible / unbounded). Tier 1/2 specs stay a short paragraph plus executable tests; full OpenSpec ceremony (propose → spec → design → tasks → archive) is reserved for Tier 3 SDD-lite/SDD-full.
• 📊 Real-time Web Operations Dashboard (cortex-ia web)
  Embedded, single-binary Web UI with real-time SSE streaming for live board state visualization, task creation, and audit logging.

---

🧭 CORTEX (MCP) vs CORTEX-IA (CLI)

Dimension	🧠 CORTEX (MCP Server)	⚙️ CORTEX-IA (Control Plane & CLI)
Nature	Standardized MCP Server (35 tools: cortex_*)	Standalone native Go binary (cortex-ia.exe)
System Plane	Epistemic & Evidence Plane	Operational Control Plane
Storage	Knowledge Graph & AST Symbol DB	ACID Transactional SQLite (~/.cortex-ia/delegation.db)
Primary Focus	• AST code symbols & call graphs • Blast radius impact analysis • Durable bug gotchas & ADR memories • Cross-session project context	• Task DAG & CAS revision state machines • Atomic claim tokens & exclusive file leases • Native-only role controllers & typed tool receipts • OpenSpec SDD validator & Web dashboard
Authority Rule	Informative & Advisory Only. Stored observations never authorize code writes or mark tasks complete.	Single Source of Truth. Task readiness, leases, transitions, and approvals exist strictly in SQLite via cortex-ia work.

---

🚀 Quick Start

1. Interactive Setup (TUI)

Launch the beautiful BubbleTea terminal interface to configure your OpenCode environment:

cortex-ia

2. Fast Non-Interactive Installation

cortex-ia install         # Installs agents, skills, plugins & registers Cortex MCP
cortex-ia sync            # Converges installed home with embedded assets
cortex-ia doctor          # Verifies health, environment paths & tool dependencies

3. Launch the Real-Time Web Dashboard

cortex-ia web --open      # Launches the local dashboard at http://127.0.0.1:7331

---

📦 Installation

Precompiled Binary (Recommended)

Download the latest prebuilt binary from the Releases page for Windows, macOS, or Linux.

Go Install

go install github.com/lleontor705/cortex-ia/cmd/cortex-ia@latest

Note: source builds do not embed the error-reporting signing secret, so they cannot send reports until you run cortex-ia report config --secret <KEY> (or export CORTEX_REPORT_SECRET before cortex-ia install, which persists it). The precompiled binary and the installers embed the secret and report out of the box — cortex-ia doctor tells you which one you have.

Install Script (Linux / macOS)

curl -sSL https://raw.githubusercontent.com/lleontor705/cortex-ia/main/scripts/install.sh | bash

Build from Source

git clone https://github.com/lleontor705/cortex-ia.git
cd cortex-ia
go build -o bin/cortex-ia ./cmd/cortex-ia

---

💻 CLI Command Surface

Commands that emit machine-readable receipts print JSON to stdout; human diagnostic commands (doctor, rollback, recover, report status, help, update) print plain text. Status queries accept show/get aliases where noted, and each subcommand group prints its usage with --help.

1. Task Boards (cortex-ia board)

Command	Syntax	Purpose
Create	cortex-ia board create <id> "<title>" "[desc]"	Initialize a durable task-board boundary
List	cortex-ia board list	List all boards with completed/total counters
Status	cortex-ia board status <id> (or show, get)	Query board metadata and full task DAG snapshot
Archive	cortex-ia board archive <id>	Mark a completed board as archived
Unarchive	cortex-ia board unarchive <id>	Restore an archived board to active
Delete	cortex-ia board delete <id>	Permanently delete an archived board and its tasks
Serve	cortex-ia board serve [--addr 127.0.0.1:7331]	Run the embedded loopback web dashboard

2. Work Items & Leases (cortex-ia work)

Command	Syntax	Purpose
Create	cortex-ia work create <id> "<title>" [--board <board>] [--depends <id>]... [--objective <text>] [--acceptance <text>] [--verify <cmd>] [--file <path>]...	Add a task to the DAG (backlog/ready) with its definition
Revise	cortex-ia work revise --plan <file|@stdin>	Safely revise an unclaimed task definition
Review Refresh	cortex-ia work review-refresh <id> --revision <n>	Rebind the review to an observed revision
Archive	cortex-ia work archive --board <id> --change <id> --workflow <sdd-lite|sdd-full> --spec-plane <openspec|cortex|hybrid>	Close independently approved SDD work
List	cortex-ia work list [--board <board-id>]	List work items, optionally scoped to one board
Status	cortex-ia work status <id> (or show, get)	Query task status, revision, claim, and active leases
Approvals	cortex-ia work approvals <id>	List historical approval records
Fingerprint	cortex-ia work fingerprint <id>	Compute current fingerprints and compare with the approval
Claim	cortex-ia work claim <id> --owner <owner> [--path <file> ...] [--ttl 15m]	Atomically acquire a task (and optional leases); returns claim_token
Controller Renew	cortex-ia work controller-renew <id> --owner <owner> --authority @stdin	Renew a live claim and its complete lease set
Renew	cortex-ia work renew <id> --claim-token <tok> [--ttl 15m]	Extend live claim TTL before expiry
Lease	cortex-ia work lease <id> --claim-token <tok> --path <file> [--ttl 15m]	Reserve one exclusive file lease; returns lease_token
Reserve	cortex-ia work reserve <id> --claim-token <tok> --path <file> [--path <file> ...] [--ttl 15m] (or file-reserve)	Reserve one or more files atomically
Lease Renew	cortex-ia work lease-renew --path <file> --lease-token <tok> [--ttl 15m]	Extend a file lease TTL while editing
Release	cortex-ia work release --path <file> --lease-token <tok>	Release one file lease
Release All	cortex-ia work release-all <id> --claim-token <tok>	Release every file lease held by a task
Transition	cortex-ia work transition <id> --claim-token <tok> [--revision <n>] --to <in_review|in_progress|blocked>	Shift task state with an optional submission receipt
Approve	cortex-ia work approve <id> --reviewer <id> --verdict <PASS|FAIL|BLOCKED|INCONCLUSIVE> [--evidence <ref>]	Record a review verdict; PASS unlocks downstream tasks
Retry	cortex-ia work retry <id> [--revision <n>]	Clear residual locks and return a blocked task to ready
Decompose	cortex-ia work decompose <id> --revision <n> --plan <file|@stdin> [--contract-file <file>]	Replace a blocked task with atomic tasks
Recover	cortex-ia work recover	Sweep expired claims/leases
Reconcile	cortex-ia work reconcile <id> --reason <text> --session <id> --revision <n>	Force-release a live-but-orphaned claim (orchestrator-only, fail-closed)
Verify Lease	cortex-ia work verify-lease --path <file> [--task <id>] [--owner <owner>] (or check-lease)	Verify an active file lease

3. OpenSpec SDD Workspace (cortex-ia openspec)

Command	Syntax	Purpose
Validate	cortex-ia openspec validate <change> --workflow <sdd-lite|sdd-full> --phase <phase> [--json]	Structurally validate planning artifacts. --workflow and --phase are required
List	cortex-ia openspec list	List active change proposals in openspec/changes/
Status	cortex-ia openspec status [change-name]	Inspect task progress and status of changes
Archive	cortex-ia openspec archive <change-name> --board <id> --workflow <sdd-lite|sdd-full> --spec-plane <openspec|cortex|hybrid>	Close independently approved SDD work
New	cortex-ia openspec new <change-name> [domain]	Scaffold a new OpenSpec change directory

4. Cortex Snapshots (cortex-ia snapshot)

Command	Syntax	Purpose
Read	cortex-ia snapshot read --project <project> --id <id> [--expected-sha256 <digest>]	Read and verify one bounded local Cortex observation

5. Git Worktrees (cortex-ia worktree)

Command	Syntax	Purpose
List	cortex-ia worktree list [--repo <repo-path>]	List authoritative Git worktrees
Validate	cortex-ia worktree validate <worktree-path> [--repo <repo-path>] [--head <commit>]	Validate a worktree contract against git porcelain

current_workspace is the only supported execution strategy. worktree create, clean, drop, delete, remove, and prune are retired and fail closed; existing worktrees are preserved.

6. Dual Ledger (cortex-ia ledger)

Command	Syntax	Purpose
Fact Add	cortex-ia ledger fact add <text> [--board <id>] [--source <src>] [--sync-cortex]	Record a verified fact (optionally synced to Cortex memory)
Fact List	cortex-ia ledger fact list [--board <board-id>] [--json]	List verified facts in chronological order
Progress	cortex-ia ledger progress record --summary <text> [--drift] [--action <act>]	Record an orchestrator progress evaluation
Status	cortex-ia ledger status [--board <board-id>] [--json]	Display the full dual-ledger report (facts + progress)

7. UI Snapshot (cortex-ia ui)

Command	Syntax	Purpose
Snapshot	cortex-ia ui snapshot [--project <path>] [--session-id <id>] [--root-session-id <id>]	Print a bounded read-only TUI snapshot

8. Documents & Diagrams (cortex-ia doc / cortex-ia diagram)

Command	Syntax	Purpose
Doc Convert	cortex-ia doc convert <file> [-o <out.md>] [--standalone] [--format <fmt>] [--max-lines <n>] [--ocr <hosted|reject>] [--json]	Convert office/PDF documents to Markdown
Doc Inspect	cortex-ia doc inspect <file> [--json]	Inspect document metadata
Diagram Validate	cortex-ia diagram validate <type> <spec.json> [--quality <standard|showcase>] [--json]	Validate diagram topology
Diagram Render	cortex-ia diagram render <type> <spec.json> [output.html] [--quality <standard|showcase>] [--json]	Render an interactive diagram HTML file
Diagram Compare	cortex-ia diagram compare <base.json> <head.json> [output.html] [--json]	Compare two architecture snapshots
Diagram Reach	cortex-ia diagram reach <type> <spec.json> --from <node-id> [--direction <upstream|downstream|both>] [--json]	Trace graph reachability from a node

9. MCP Management (cortex-ia mcp)

Command	Syntax	Purpose
Add (preset)	cortex-ia mcp add <name> --preset [--dry-run]	Register a managed catalog MCP preset
Add (local)	cortex-ia mcp add <name> --local [--env KEY=VALUE]... -- <command> [args...]	Register a managed custom local MCP server
Add (remote)	cortex-ia mcp add <name> --remote <url> [--header KEY=VALUE]... [--dry-run]	Register a managed custom remote MCP server
List	cortex-ia mcp list [--json]	List managed MCP entries and ownership
Adopt	cortex-ia mcp adopt <name> [--dry-run]	Accredit an existing user-owned MCP entry that already equals a managed preset
Remove	cortex-ia mcp remove <name> [--dry-run]	Deregister a managed MCP entry

--preset, --local, and --remote are mutually exclusive: exactly one is required per add.

10. Reporting (cortex-ia report)

Command	Syntax	Purpose
Report Error	cortex-ia report error --code <code> --message <msg> [--details <text|@stdin>] (or send)	Generate and send a signed error report
Report Config	cortex-ia report config [--endpoint <url>] [--secret <key>] [--enable|--disable]	Configure the reporting endpoint
Report Flush	cortex-ia report flush	Retry bounded queued reports
Report Status	cortex-ia report status	Show the current reporting configuration

The former cortex-ia hook subcommand is retired and fails closed with a retired-surface error.

11. Model Management (cortex-ia model)

Command	Syntax	Purpose
List	cortex-ia model list	List all configured model assignments
Get	cortex-ia model get <agent>	Show the model assigned to an agent
Set	cortex-ia model set <agent> <provider/model[#variant]> [--effort <level>]	Assign a model to an agent
Unset	cortex-ia model unset <agent>	Remove an agent's model assignment
Doctor	cortex-ia model doctor	Check model configuration health
Catalog	cortex-ia model catalog	Read-only list of available providers, models, and variants

12. Usage Statistics (cortex-ia stats)

Command	Syntax	Purpose
Stats	cortex-ia stats [--json]	Print bounded read-only usage statistics (--json for machine-readable output)

13. Maintenance & Lifecycle (install / sync / doctor / rollback / recover / uninstall / update)

Command	Syntax	Purpose
Install	cortex-ia install [--target <list>] [--dry-run] [--overwrite] [--theme]	Install assets and plugins (default target: opencode); --theme applies the bundled cortex theme (opencode target only)
Sync	cortex-ia sync [--target <list>] [--dry-run] [--overwrite]	Reconcile the installed home with the current asset set
Doctor	cortex-ia doctor	Read-only installation health report
Rollback	cortex-ia rollback [backup-id] / cortex-ia rollback list	Restore a backup or list available backups
Recover	cortex-ia recover [list] / cortex-ia recover <journal-id>	List or restore pending recovery journals
Uninstall	cortex-ia uninstall [--target <list>] [--dry-run]	Remove the accredited installation
Update	cortex-ia update [--check] [--scheduled] [--allow-checksum-updates] (or upgrade)	Check for / install the latest release
Update Schedule	cortex-ia update schedule <enable|disable|status>	Manage the headless daily check-only update task

--theme, --scheduled, and --allow-checksum-updates are documented with their full flag tables in docs/getting-started/configuration.md.

---

🤖 Multi-Agent Coordination Topology

1. orchestrator (Primary): Triage, startup alignment, Cortex session lifecycle, and DAG dispatch. Never claims tasks or holds file leases.
2. discovery (Subagent): Inspects skills, toolchains, engines, and project architecture into the durable .cortex-ia/discovery.md profile.
3. investigate (Subagent): Root-cause diagnosis, AST blast radius inspection, spikes, and read-only diagnostic audits.
4. planner (Subagent): Writes OpenSpec delta specifications (RFC 2119), Given/When/Then contracts, and decomposes task DAGs under the tiered workload policy.
5. implement (Subagent): Atomically claims one task, reserves exclusive file leases, runs fast TDD loops, and transitions to review via typed tools.
6. reviewer (Subagent): Independently verifies git diffs, executes test oracles, and grants PASS approval to unlock downstream dependencies.

---

🚦 3-Tier Organic Routing Model

Cortex-IA matches user requests to the smallest, safest workflow using a three-tier model:

Tier	Workflows	Characteristics	Execution Model
Tier 1: Fast Path	direct-answer, discovery, investigate, spike, hotfix, fast-tdd, ops-task	Direct execution without task DAG overhead. Specialized for Q&A, onboarding, root-cause diagnosis, or fast unit TDD.	Single-turn dispatch via orchestrator ➔ subagent ➔ orchestrator.
Tier 2: Bounded Unitary Task	direct-change	Single-domain, low-risk changes with fast verification. Uses board_id: "default".	Claim task ➔ exclusive file lease ➔ edit & test ➔ cortex_ia_work_transition ➔ independent review gate.
Tier 3: Coordinated SDD	sdd-lite, sdd-full	High-complexity, multi-file features or cross-domain architectural changes.	Stable initiative board ➔ OpenSpec delta specs ➔ DAG decomposition under the tiered workload policy ➔ parallel implementation minions ➔ adversarial review.

---

🛡️ Transactional Safety Guarantees

• Dry-Run Determinism: --dry-run calculates the exact execution plan without making any disk writes.
• Cross-Process File Locking: Every mutating command holds a robust cross-process file lock (LockFileEx on Windows, flock on Unix) preventing concurrent installer races.
• Verified Backups & Rollbacks: Snapshots affected configuration files under ~/.cortex-ia/backups/ and automatically rolls back if an apply phase encounters an error.
• Strict Path Sandboxing: Leases and workspace operations reject directory traversal (..) and absolute path escape attempts.

---

📚 Documentation Reference

Getting Started

• 📖 Quickstart Guide — Guided first-time setup and onboarding
• ⚙️ Installation — Binary installation methods, Homebrew, and auto-update
• 🔧 Configuration — CLI reference, environment variables, and state layout
• 💻 Non-Interactive Mode — Scripting, CI, and Docker recipes

Architecture & Design

• 🏛️ Architecture Deep-Dive — Internal engine layers, models, and SQLite concurrency
• 🧠 Cortex Memory & Graph — AST symbol graph, blast radius, and durable observations
• 🤖 Agent Roles & Contracts — 6-role coordination topology and typed receipt contracts
• 🧩 Components & MCP — Deployed assets, MCP presets, and custom servers
• 📑 SDD Workflow Guide — Specification-Driven Development lifecycle with OpenSpec

Operations & Safety

• 🔒 Security & Recovery — Safety guarantees, backups, rollback, and recovery
• 🔄 Backups & Rollback — Backup lifecycle, retention, and explicit rollback
• 🖥️ Supported Platforms — OS support, paths, and terminal requirements
• 🐳 Docker E2E Testing — Container-based test suite

MCP & Integration

• 🔌 MCP Manager — Catalog presets, custom servers, and ownership
• 🔑 Release Signing Keys — Trust bundle format and key ceremony

Qualification & CI

• 📋 CI & Distribution Inputs — Workflow provenance and toolchain baseline
• 🧪 SDK & Plugin Qualification — Harness SDK lock and isolation
• 🔗 MCP Integration Qualification — Context7 and Cortex MCP evidence

Developer Guide

• 🗺️ Repository Map — Directory-by-directory codebase layout
• 📇 Reference Map — CLI commands, Go packages, and types index
• 🧠 Mental Model — End-to-end flow explanation
• 🔌 MCP Boundaries — Epistemic vs operational authority separation
• 📊 Dashboard & TUI — BubbleTea architecture and screen states
• 🔗 Integrations & CI/CD — Release pipeline and workflows
• 📝 Maintainer Playbook — Release runbook and dependency maintenance
• 🔄 Sync, State & Backup — Local state persistence and reconciliation
• 🧩 Interfaces & Contracts — Core Go interfaces reference
• 📘 Project & Extension Guide — Adding skills, agents, commands, plugins
• 🔀 SDD Coordination — Work lifecycle and authority rules

Monitoring

• 📊 Report Hub Snapshot — Railway service monitoring

---

📄 License

MIT License · Built with ❤️ by Luis Leon and contributors.