Metadata-Version: 2.4
Name: claude-cortex
Version: 1.3.0
Summary: Context orchestration CLI with curated agents, rules, skills, and management tools for Claude Code
Author-email: Nicholas Ferguson <ncf423@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/NickCrew/claude-cortex
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: argcomplete>=3.2
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.47.0
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: jsonplate>=0.0.1
Requires-Dist: jsonschema>=4.25.1
Provides-Extra: ai
Requires-Dist: fastembed>=0.7.4; extra == "ai"
Requires-Dist: numpy>=1.24.0; extra == "ai"
Provides-Extra: llm
Requires-Dist: anthropic>=0.18.0; extra == "llm"
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.100.0; extra == "dashboard"
Requires-Dist: uvicorn>=0.20.0; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
Requires-Dist: types-psutil>=5.9.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: PyYAML>=6.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: python-semantic-release>=9.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: fastembed>=0.7.4; extra == "all"
Requires-Dist: numpy>=1.24.0; extra == "all"
Requires-Dist: anthropic>=0.18.0; extra == "all"
Requires-Dist: fastapi>=0.100.0; extra == "all"
Requires-Dist: uvicorn>=0.20.0; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/images/cortex-banner.png" alt="Cortex — Multi-Model Development Orchestration" width="100%" />
</p>

<p align="center">
  <a href="https://github.com/NickCrew/claude-cortex/actions/workflows/test.yml"><img src="https://github.com/NickCrew/claude-cortex/actions/workflows/test.yml/badge.svg" alt="Tests" /></a>
  <a href="https://github.com/NickCrew/claude-cortex/actions/workflows/type-check.yml"><img src="https://github.com/NickCrew/claude-cortex/actions/workflows/type-check.yml/badge.svg" alt="Type Check" /></a>
  <a href="https://pypi.org/project/claude-cortex/"><img src="https://img.shields.io/pypi/v/claude-cortex" alt="PyPI" /></a>
  <a href="https://github.com/NickCrew/claude-cortex/blob/main/LICENSE"><img src="https://img.shields.io/github/license/NickCrew/claude-cortex" alt="License" /></a>
</p>

<p align="center">
  Multi-model development orchestration for Claude Code, Codex, and Gemini.
</p>

<p align="center">
  <a href="https://cortex.atlascrew.dev/">Documentation</a> &middot;
  <a href="#install">Install</a> &middot;
  <a href="#quick-start">Quick Start</a>
</p>

---

Cortex is a development orchestration framework that coordinates AI agents across model providers. It enforces quality gates — independent code review, test coverage audits, and lint checks — so that no agent grades its own homework. The result is a structured, auditable development workflow where Claude, Codex, and Gemini collaborate with built-in verification at every step.

## How It Works

### Multi-model review with no self-review

Cortex's core principle: **the agent that writes the code never reviews it.** When Codex implements a feature, the review is routed to Claude first, then to a different model family, with same-model review as a last resort. Every review produces a structured artifact with severity levels and a pass/fail verdict.

```
Codex implements → Claude reviews → Codex remediates → Claude re-reviews
                   ↓ (unavailable)
                   Gemini reviews (fallback)
                   ↓ (unavailable)
                   Fresh-context Codex reviews (last resort)
```

### Agent-loops: progressive quality gates

Every code change flows through three sequential loops, each with circuit breakers and escalation rules:

```
Code Change Loop    →  Implement → Independent review → Remediate P0/P1 → Re-review (max 3 cycles)
Test Writing Loop   →  Audit gaps → Write tests → Verify → Re-audit (max 3 cycles)
Lint Gate           →  Discover linter → Auto-fix → Check → Remediate (max 2 cycles)
```

P0/P1 findings must be resolved before the loop exits. P2/P3 findings are filed as issues automatically. If circuit breakers trigger, the agent stops and escalates to a human — no infinite remediation loops.

### Skill recommendations

Skills are suggested automatically as you work via a two-layer pipeline: fast keyword matching on every prompt (~50ms), with optional semantic matching for deeper recommendations. The TUI runs a background watch daemon for continuous suggestions.

## What's Inside

| Path | Purpose |
|---|---|
| `agents/` | Agent definitions (specialized reviewers, implementers) |
| `skills/` | Reusable skill modules — workflow guidance, review prompts, quality standards |
| `rules/` | Behavioral guardrails and coding conventions |
| `hooks/` | Automation hooks (skill suggestions, validation gates) |
| `claude_ctx_py/` | Python CLI and TUI implementation |

### Key skills

- **`agent-loops`** — The core workflow: structured implementation with independent review, test audit, and lint gates. Includes provider-aware review scripts with fallback chains.
- **`test-review`** — Test quality and coverage auditing across modules.
- **`doc-claim-validator`** — Validates documentation claims against actual code.
- **`doc-maintenance`** — Systematic documentation audit and lifecycle management.

## Install

```bash
# Recommended
pipx install claude-cortex

# Alternative
pip install claude-cortex
```

For development:

```bash
git clone https://github.com/NickCrew/claude-cortex.git
cd claude-cortex
pip install -e ".[dev]"
```

## Quick Start

```bash
cortex install link          # Symlink bundled assets into ~/.claude
cortex install post          # Shell completions + man pages (optional)
cortex status                # Check what's active
cortex tui                   # Launch the terminal UI
```

## CLI Overview

```bash
cortex <command> [options]
```

| Command | What it does |
|---|---|
| `status` | Show active agents, rules, hooks, skills |
| `agent list\|status` | Manage agent definitions |
| `skills list\|info\|recommend` | Discover and inspect skills |
| `rules list\|activate` | Manage behavioral rules |
| `hooks list\|install` | Install and validate hooks |
| `mcp list\|diagnose` | MCP server discovery and diagnostics |
| `ai recommend\|watch` | AI-powered skill recommendations |
| `review` | Run review workflows |
| `tui` | Launch terminal UI |
| `docs` | Browse bundled documentation |
| `install\|uninstall` | Manage Cortex installation |

Run `cortex --help` or `cortex <command> --help` for details.

## Development

```bash
just test                    # Run test suite
just lint                    # Check formatting (Black)
just type-check              # Strict mypy
just docs                    # Serve docs locally
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Documentation

Full documentation at **[cortex.atlascrew.dev](https://cortex.atlascrew.dev/)**.

- [Getting Started](docs/guides/getting-started.md)
- [Commands Reference](docs/guides/commands.md)
- [Skills Guide](docs/guides/skills.md)
- [Architecture](docs/architecture/README.md)
- [Skill Recommendation Engine](docs/architecture/skill-recommendation-engine.md)
- [CHANGELOG](CHANGELOG.md)

## License

MIT. See [LICENSE](LICENSE).
