GitHub - lleontor705/cortex-ia: AI Agent Ecosystem Configurator — persistent memory, SDD workflow, inter-agent messaging, multi-CLI orchestration

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.
🛡️ Mandatory Independent Review Gates (work approve)
Implementers cannot self-approve. An independent reviewer agent must verify test suites and recorded evidence before marking any task complete.
🧹 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 proposals, RFC 2119 delta specifications, and task decompositions bounded to ≤350 LOC.
📊 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

orchestrator (Primary): Triage, startup alignment, Cortex session lifecycle, and DAG dispatch. Never claims tasks or holds file leases.
discovery (Subagent): Inspects skills, toolchains, engines, and project architecture into the durable .cortex-ia/discovery.md profile.
investigate (Subagent): Root-cause diagnosis, AST blast radius inspection, spikes, and read-only diagnostic audits.
planner (Subagent): Writes OpenSpec delta specifications (RFC 2119), Given/When/Then contracts, and decomposes task DAGs (≤350 LOC).
implement (Subagent): Atomically claims one task, reserves exclusive file leases, runs fast TDD loops, and transitions to review via typed tools.
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 (≤350 LOC) ➔ 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.

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.github		.github
.husky		.husky
cmd		cmd
docs		docs
e2e		e2e
internal		internal
openspec/changes		openspec/changes
scripts		scripts
testdata/report_hub_fixtures		testdata/report_hub_fixtures
tools		tools
web		web
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.es.md		CODE_OF_CONDUCT.es.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.es.md		CONTRIBUTING.es.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS.md		CONTRIBUTORS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.es.md		README.es.md
README.md		README.md
SECURITY.es.md		SECURITY.es.md
SECURITY.md		SECURITY.md
SUPPORT.es.md		SUPPORT.es.md
SUPPORT.md		SUPPORT.md
TRANSLATIONS.md		TRANSLATIONS.md
go.mod		go.mod
go.sum		go.sum
llms-full.txt		llms-full.txt
llms.txt		llms.txt
mkdocs.yml		mkdocs.yml
package-lock.json		package-lock.json
package.json		package.json
requirements-docs.txt		requirements-docs.txt

Latest commit

History

Folders and files

Repository files navigation

⚡ What is Cortex-IA?

🌟 Key Superpowers

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

🚀 Quick Start

1. Interactive Setup (TUI)

2. Fast Non-Interactive Installation

3. Launch the Real-Time Web Dashboard

📦 Installation

Precompiled Binary (Recommended)

Go Install

Install Script (Linux / macOS)

Build from Source

💻 CLI Command Surface

1. Task Boards (cortex-ia board)

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

3. OpenSpec SDD Workspace (cortex-ia openspec)

4. Cortex Snapshots (cortex-ia snapshot)

5. Git Worktrees (cortex-ia worktree)

6. Dual Ledger (cortex-ia ledger)

7. UI Snapshot (cortex-ia ui)

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

9. MCP Management (cortex-ia mcp)

10. Reporting (cortex-ia report)

11. Model Management (cortex-ia model)

12. Usage Statistics (cortex-ia stats)

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

🤖 Multi-Agent Coordination Topology

🚦 3-Tier Organic Routing Model

🛡️ Transactional Safety Guarantees

📚 Documentation Reference

Getting Started

Architecture & Design

Operations & Safety

MCP & Integration

Qualification & CI

Developer Guide

Monitoring

📄 License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages