Cortex Operations

The Cortex is Agent Hive's orchestration engine - the central nervous system that reads project state, analyzes dependencies, and coordinates AI agents.

Cortex Modes

1. Full LLM Analysis (Default)

Runs complete analysis using an LLM to identify blocked tasks, suggest state updates, and detect new project requests.

# Run full analysis
uv run python -m src.cortex

# Or using make
make cortex

What it does:

• Reads GLOBAL.md and all AGENCY.md files
• Calls LLM to analyze system state
• Identifies blocked tasks and recommendations
• Applies state updates to project files
• Updates last_cortex_run timestamp

Requirements:

• OPENROUTER_API_KEY environment variable
• OPENROUTER_MODEL (optional, defaults to anthropic/claude-haiku-4.5)

2. Ready Work Detection (Fast, No LLM)

Quickly finds projects ready for an agent to claim without requiring API calls.

# Human-readable output
uv run python -m src.cortex --ready

# JSON output for programmatic use
uv run python -m src.cortex --ready --json

Ready criteria:

• status == 'active'
• blocked == false
• owner == null (unclaimed)
• No unresolved dependencies.blocked_by

3. Dependency Graph Analysis (Fast, No LLM)

Visualizes project dependencies and detects cycles.

# Human-readable tree view
uv run python -m src.cortex --deps

# JSON output
uv run python -m src.cortex --deps --json

Output includes:

• All projects with their status
• Dependency relationships (blocks/blocked_by)
• Cycle detection warnings
• ASCII dependency tree

Command Reference

| Command | Description | |---------|-------------| | uv run python -m src.cortex | Full LLM analysis | | uv run python -m src.cortex --ready | Find ready work | | uv run python -m src.cortex --deps | Show dependency graph | | uv run python -m src.cortex --json | JSON output (with --ready or --deps) | | uv run python -m src.cortex --path /custom/path | Use custom base path |

Understanding Output

Ready Work Output

============================================================
READY WORK
============================================================
Timestamp: 2025-01-15T14:30:00
Found 2 project(s) ready for work

!!  feature-auth
    Priority: high
    Tags: feature, security
    Path: projects/feature-auth/AGENCY.md

!   docs-update
    Priority: medium
    Tags: documentation
    Path: projects/docs-update/AGENCY.md
============================================================

Priority indicators:

• !!! - critical
• !! - high
• ! - medium
• - low

Dependency Graph Output

============================================================
DEPENDENCY GRAPH
============================================================
BLOCKED PROJECTS:
----------------------------------------
*** phase-2
    Status: active
    Blocked by: phase-1
    Reason: Blocked by uncompleted: phase-1

UNBLOCKED PROJECTS:
----------------------------------------
    phase-1 [active]
      Blocks: phase-2
    standalone [active]

DEPENDENCY TREE:
----------------------------------------
[*] phase-1
  [*] phase-2
[*] standalone

Legend: [+] completed  [*] active  [!] blocked  [-] pending
============================================================

Cycle Detection

The Cortex detects circular dependencies that can never be resolved:

!!! CYCLES DETECTED !!!
    project-a -> project-b -> project-c -> project-a

To fix cycles:

1. Review the dependency chain
2. Remove or modify one of the blocked_by relationships
3. Re-run --deps to verify resolution

GitHub Actions Integration

The Cortex runs automatically every 4 hours via .github/workflows/cortex.yml:

on:
  schedule:
    - cron: '0 */4 * * *'  # Every 4 hours

Workflow steps:

1. Checkout repository
2. Install dependencies with uv
3. Run Cortex
4. Commit changes if state was updated

Required secrets:

• OPENROUTER_API_KEY

Troubleshooting

"OPENROUTER_API_KEY not set"

# Set in .env file
echo "OPENROUTER_API_KEY=sk-or-v1-xxxxx" >> .env

# Or export directly
export OPENROUTER_API_KEY="sk-or-v1-xxxxx"

"GLOBAL.md not found"

Ensure you're running from the hive root directory:

cd /path/to/agent-hive
uv run python -m src.cortex

Or specify the path:

uv run python -m src.cortex --path /path/to/agent-hive

"No projects found"

Verify projects directory exists with AGENCY.md files:

ls projects/*/AGENCY.md

LLM Response Parse Error

The Cortex expects JSON from the LLM. If parsing fails:

• Check API key validity
• Try a different model in OPENROUTER_MODEL
• Check console output for raw response

Programmatic Usage

from src.cortex import Cortex

# Initialize
cortex = Cortex(base_path="/path/to/hive")

# Discover projects
projects = cortex.discover_projects()

# Get ready work
ready = cortex.ready_work(projects)

# Check if specific project is blocked
blocking_info = cortex.is_blocked("project-id", projects)

# Get full dependency summary
summary = cortex.get_dependency_summary(projects)