claude-cortex 1.2.0

Context orchestration CLI with curated agents, rules, skills, and management tools for Claude Code

Context orchestration for Claude Code, Codex, and Gemini — curated agents, skills, rules, hooks, and a Python CLI for management.

Documentation · Install · Quick Start

Why Cortex

• Curated context assets for Claude Code (agents/, skills/, rules/, hooks/)
• A Python CLI (cortex) for activation, validation, TUI workflows, diagnostics, and exports
• Built-in support for MCP docs, memory capture, and review gates

Feature Highlights

Original Cortex Skills

Cortex includes four foundational skills that drive quality across development workflows:

agent-loops — Structured Implementation & Verification

• Skill file: skills/agent-loops/SKILL.md
• Purpose: Multi-phase implementation loop with built-in verification, audit, and independent review gates
• When to use: Any feature implementation, bug fix, or refactoring task
• Workflow: Plan → Implement → Verify → Independent review/audit with same-model shell-outs kept for last resort
• CLI integration: Complements cortex review command:

cortex review --dry-run                    # Preview review gates
cortex review -c feature -c debug          # Full review workflow

test-review — Quality Assurance & Coverage Analysis

• Skill file: skills/test-review/SKILL.md
• Purpose: Audit test quality and coverage across modules
• When to use: After test suite changes, coverage gaps, or brittle tests
• Features: Identifies gaps, suggests improvements, validates test patterns

doc-claim-validator — Documentation Accuracy Auditing

• Skill file: skills/doc-claim-validator/SKILL.md
• Purpose: Validates that documentation claims match codebase reality
• When to use: Before releases, after major refactors, periodic audits
• Features: Extracts verifiable assertions (file paths, code patterns), checks against actual code

doc-maintenance — Documentation Lifecycle Management

• Skill file: skills/doc-maintenance/SKILL.md
• Purpose: Systematic documentation audit and maintenance
• When to use: Documentation may be stale, outdated references, inconsistent structure
• Features: Identifies orphaned docs, updates cross-references, improves navigation

Skills command suite

• Discover and inspect skills:

cortex skills list
cortex skills info agent-loops
cortex skills recommend

• Collect feedback and ratings:

cortex skills feedback agent-loops helpful --comment "High signal loop guidance"
cortex skills rate agent-loops --stars 5 --review "Reliable workflow"

Skill Recommendations (automatic)

Skills are suggested automatically via a two-layer pipeline:

• Layer 1 (hook): Keyword matching against skill-rules.json on every prompt (~50 ms)
• Layer 2 (recommender): Semantic, rule-based, agent-based, and historical strategies via SkillRecommender (~100-200 ms, optional)

Results from both layers are merged and deduplicated — keyword matches first, then richer recommendations. The hook gracefully falls back to Layer 1 if the full package isn't installed.

The TUI auto-starts the watch daemon on launch for continuous background recommendations. See Skill Recommendation Engine for the full architecture.

AI command suite

• Recommendations and auto-activation:

cortex ai recommend
cortex ai auto-activate

• Continuous watch mode (auto-started by TUI):

cortex ai watch --interval 2.0 --threshold 0.7 --dir .

• Learning ingestion and export:

cortex ai ingest-review .agents/reviews/latest.md
cortex ai export --output ai-recommendations.json

Repository Layout

Path	Purpose
agents/	Agent definitions used by Claude Code
skills/	Reusable skill modules with metadata and guidance
rules/	Rule modules for behavior and quality guardrails
hooks/	Hook definitions and validation assets
commands/	Slash-command style command assets
claude_ctx_py/	Python CLI implementation
docs/	Documentation source for guides/reference
schemas/	Validation schemas
tests/	Unit and integration tests

Installation (pip / pipx)

Install released CLI

# Recommended
pipx install claude-cortex

# Alternative
python3 -m pip install claude-cortex

Local development install

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

Quick Start

# Link bundled assets into ~/.claude
cortex install link

# Optional post-install helpers (completions + manpages)
cortex install post

# Check current state
cortex status

# Launch TUI
cortex tui

CLI Arguments and Commands

Current global arguments:

• --scope {auto,project,global}
• --cortex-root PATH (alias: --plugin-root)
• --skip-wizard (alias: --no-init)

Usage pattern:

cortex [--scope {auto,project,global}] [--cortex-root PATH] [--skip-wizard] <command> [<args>]

Documented command groups in this README:

• agent
• rules
• hooks
• skills
• mcp
• statusline
• tui
• ai
• export
• install
• memory
• plan
• docs
• dev
• file
• uninstall
• status
• review

Run help anytime:

cortex --help
cortex <command> --help

Common Workflows

Using Original Cortex Skills

Feature implementation with agent-loops:

# Start implementation with built-in verification gates
# Reviews prefer Claude, keep same-model shell-outs last, and preserve artifacts
cortex review --dry-run                    # Preview what will be reviewed
cortex review -c feature -c debug          # Run full review workflow

Quality assurance with test-review:

# Audit test quality and identify coverage gaps
cortex skills info test-review             # View skill details
# Then invoke: /test-review in Claude Code to audit your test suite

Documentation accuracy with doc-claim-validator:

# Validate documentation matches codebase reality
cortex skills info doc-claim-validator     # View skill details
# Then invoke: /doc-claim-validator in Claude Code to audit docs

Documentation maintenance with doc-maintenance:

# Perform systematic documentation audit
cortex skills info doc-maintenance         # View skill details
# Then invoke: /doc-maintenance in Claude Code for maintenance workflow

Agent + skill management

cortex agent list
cortex agent status
cortex skills list
cortex skills feedback agent-loops helpful --comment "High signal loop guidance"
cortex skills rate agent-loops --stars 5 --review "Reliable workflow"

MCP diagnostics

cortex mcp list
cortex mcp diagnose

AI recommendations

cortex ai recommend
cortex ai auto-activate
cortex ai watch

Development

Preferred local commands

command -v committer
command -v tx

• Use committer for atomic commits
• Use tx for local workflow/service orchestration

Build, test, quality

just install
just test
just lint
just type-check

Additional useful targets:

just test-unit
just test-integration
just test-cov
just docs
just docs-build
just build

Docs preview

cd docs
bundle exec jekyll serve --livereload

Documentation Index

• docs/index.md
• docs/README.md
• docs/guides/getting-started.md
• docs/guides/commands.md
• docs/guides/skills.md
• docs/guides/asset-manager.md
• docs/guides/prompt-library.md
• docs/tutorials/index.md
• docs/reference/index.md
• docs/reference/configuration.md
• docs/reference/api/index.md
• docs/architecture/README.md
• docs/architecture/skill-recommendation-engine.md
• CONTRIBUTING.md
• CHANGELOG.md
• CREDITS.md

License

MIT. See LICENSE.