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

uv run python -m src.cortex

uv run python -m src.cortex --ready

uv run python -m src.cortex --deps

uv run python -m src.cortex --json

uv run python -m src.cortex --path /custom/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)