Cortex

iEvo kernel source — provider-agnostic agent templates, skills, and pipeline conventions.

What

Cortex stores the iEvo kernel as Jinja2-templated source and builds provider-specific artifacts at release time. The iEvo CLI downloads the latest Cortex release asset via HTTPS during ievo init.

For detailed architecture, see docs/ARCHITECTURE.md.

Structure

cortex/
├── src/
│   └── cortex/          # Python package (cli.py, compile.py, version.py)
├── templates/
│   ├── kernel/          # Brain region .md files + consciousness.md.j2
│   ├── agents/          # Agent templates (provider-agnostic)
│   └── codex/           # Codex target (BUILD_TARGET.md placeholder)
├── tests/               # Build script tests
└── .github/
    └── workflows/
        └── release.yml  # CI: push to main → build → validate → GitHub Release + PyPI

Template variables

The templates/kernel/consciousness.md.j2 template supports the following variables:

Variable	Type	Source	Example
cortex_version	string	--tag CLI argument	"v1.2.0"

Variables are injected into the template using standard Jinja2 syntax:

<!-- cortex {{ cortex_version }} -->

Release assets

Each GitHub Release includes cortex-<tag>.tar.gz containing:

cortex-<tag>.tar.gz
├── iEVO.md             # Rendered from templates/kernel/consciousness.md.j2 (provider-agnostic)
├── claude/             # Claude Code provider artifacts
│   └── agents/
│       └── *.md        # Agent templates rendered for Claude Code
└── codex/              # OpenAI Codex provider artifacts
    └── BUILD_TARGET.md # Placeholder — full templates in future REQs

Building locally

uv run cortex compile
# Output: dist/cortex-<version>.tar.gz

Version is auto-read from package metadata (CalVer) — no --tag argument needed.

Link validation runs by default. Add --skip-validate for faster local builds when lychee is not installed:

uv run cortex compile --skip-validate

Link validation runs automatically in CI after the build.

Running tests

uv run pytest tests/
# With coverage:
uv run pytest tests/ --cov

Dependencies

All dependencies are managed by uv — see pyproject.toml for the full list. Lychee (Markdown link validator) is a Rust binary used in CI only — not a Python dependency.

Contributing

Prerequisites

• uv (required) — Python package manager and virtualenv tool:

  curl -LsSf https://astral.sh/uv/install.sh | sh

• lychee (optional) — Markdown link validator. Only needed to run cortex compile without --skip-validate. Link validation runs automatically in CI.

Quick start

git clone https://github.com/ievo-ai/cortex
cd cortex
uv sync --extra dev        # installs cortex + pytest + ruff + mypy + watchfiles
uv run cortex dev --watch  # hot-reload on templates/ changes

Run tests:

uv run pytest tests/

Godfather dev mode

When developing cortex templates inside the godfather workspace, you can point .ievo/iEVO.md at the cortex build output so cortex dev --watch rebuilds are immediately picked up by godfather's context.

From the godfather root:

# Point iEVO.md at cortex dev output (live rebuilds)
ln -sf ../repos/cortex/dist/iEVO.md .ievo/iEVO.md

# Restore (points back to CLI-distributed template)
ln -sf ../repos/cli/src/ievo/marketplace/templates/iEVO.md .ievo/iEVO.md

Verify the symlink with:

ls -la .ievo/iEVO.md

Integration

The iEvo CLI downloads and unpacks the latest release asset:

ievo init          # Downloads latest Cortex release automatically
ievo cortex build  # Rebuild locally from source (power-user path)

See: ievo-ai/cli