---
layout: default
title: Overview
nav_order: 1
permalink: /
---

# Cortex - Documentation Index

> Version 3.0.1 · Last updated March 6, 2026

Cortex keeps your agents, commands & workflows in perfect sync.
    
      Activate a fully curated context stack for Claude Code: purpose-built slash commands,
      dependency-aware agents, reusable skills, and a Python CLI that all speak the same
      language. Configure once, deploy everywhere.

    <div class="hero__cta">
      <a href="https://github.com/NickCrew/claude-cortex" target="_blank" rel="noopener">
        View on GitHub →
      </a>
      <a class="secondary" href="#installation">Install the package</a>
    </div>

    <div class="hero__pills">
      <span>Claude Code Native</span>
      <span>Python CLI</span>
      <span>MCP Ready</span>
      <span>Purple Ops Theme</span>
    </div>
  
  
    Cortex blueprint

## Overview

Cortex is a comprehensive context management toolkit for Claude Code. Install the Python package to get curated agents, slash commands, skills, rules, and hooks for systematic software development.

28
    
Agents
    
Specialized personas

124
    
Skills
    
Progressive disclosure packs

116
    
Commands
    
Slash command assets

### Quick Links

  → TUI Tutorial
  Getting Started
  Command Reference
  Asset Manager
  Worktree Manager
  Hooks
  ▶ Presentations
  Install
  AI Intelligence
  Collaboration Flow
  Project Structure

---

## ▶ Presentation Decks {#presentations}

Reveal.js presentations for demos, enablement sessions, and executive briefings.

→ Cortex Intro Overview
    
High-level story of the platform: AI intelligence, watch mode, asset manager, visual excellence, and multi-LLM consult. Great for quick introductions.
    
Topics: AI Intelligence • Watch Mode • Asset Manager • Visual Excellence • Multi-LLM Consult • Recent Improvements
    Launch →
    
      9 slides
      Screenshots included

→ Technical Deep Dive
    
Deep focus on activation, recommendations, intelligence signals, watch mode loops, skill ratings, and plugin/CLI integration.
    
Topics: Activation Pipeline • Intelligence Signals • Watch Mode • Skill Ratings • Install Flow • Plugin + CLI
    Launch →
    
      13 slides
      Technical focus

→ Executive Overview & Roadmap
    
Executive-friendly narrative with capability highlights, recent improvements, adoption plan, and phased roadmap.
    
Topics: Business Value • Capability Highlights • Recent Improvements • Roadmap • Adoption • Risks
    Launch →
    
      9 slides
      Strategy + roadmap

▶ Feature Catalog (TUI + CLI)
    
Comprehensive catalog of every capability, with how-to guidance, docs links, and up-to-date TUI screenshots.
    
Coverage: AI Assistant • Watch Mode • Agents • Skills • Command Palette • Slash Commands • Modes • Profiles • Principles • Flags • Workflows • Scenarios • Worktrees • Asset Manager • Hooks • Backups • Memory • MCP • Export • Setup Wizard • Shortcuts • CLI
    Launch →
    
      26 slides
      Docs-linked catalog

  ℹ How to View: Open presentations directly in your browser or serve locally with `python3 -m http.server 8080` from the presentations directory. See presentations/README.md for keyboard controls and customization guide.

---

## → Tutorials {#tutorials}

Hands-on tutorials to master cortex from beginner to advanced.

→ Getting Started with Cortex TUI
    
Master the Terminal User Interface in 20-30 minutes. Learn navigation, agent management, workflows, and when to use CLI vs TUI. Perfect for beginners and visual learners.
    
You'll Learn: TUI Navigation • Agents & Modes • Skills & Workflows • Command Palette • Export • AI Assistant • MCP Servers • Profiles
    Start Tutorial →
    
      ⏳ 20-30 minutes
      ✓ 15+ checkpoints
      → 60+ examples

  → New to cortex? Start with the TUI tutorial above. It includes CLI alternatives for power users and clear markers for advanced features. View all tutorials →

---

## → AI Intelligence & Automation {#ai-intelligence}

Stay in Claude Code flow with intelligent, self-managing context:

ℹ Context-Aware Recommendations
    
Detects project signals and suggests agents/skills with confidence scores.

→ Auto-Activation + Watch Mode
    
Watch mode monitors changes and auto-activates high-confidence agents.

→ Skill Recommendations
    
Two-layer pipeline: keyword matching (Layer 1) + semantic/historical strategies (Layer 2).

→ Workflow Orchestration
    
Run workflows and scenarios, then export or share context snapshots.

### Watch Mode - Real-Time Monitoring

```bash
# Start watch mode (foreground, no daemon)
cortex ai watch

# Monitor as you code:
# • Git commits detected
# • Context analyzed instantly
# • Agents auto-activated
# • Statistics tracked

# Press Ctrl+C to stop
```

**Example output:**

```
[10:33:12] 🔍 Context detected: Backend, Auth
  3 files changed

  ℹ Recommendations:
     🔴 security-auditor [AUTO]
        95% - Auth code detected

[10:33:12] → Auto-activating 1 agents...
     ✓ security-auditor
```

### TUI AI Assistant

```bash
cortex tui
# Press '0' for AI Assistant view
# Press 'A' to auto-activate recommendations
```

Interactive AI view shows:

- → Intelligent recommendations with confidence scores
- → Workflow predictions from learned patterns
- → Context analysis (files, detected contexts)
- → Quick actions (keyboard shortcuts)

### CLI Commands

```bash
# Get recommendations for current context
cortex ai recommend

# Auto-activate high-confidence agents
cortex ai auto-activate

# Export recommendations to JSON
cortex ai export --output recommendations.json

# Record successful session for learning
cortex ai record-success --outcome "feature complete"
```


  ✅ Stability update: AI recommendations, auto-activation, and watch mode have been hardened. Context activation now tracks consistently across sessions and exports.

### Documentation

- [AI Intelligence Guide](AI_INTELLIGENCE.html) - Complete AI system overview
- [LLM Intelligence Guide](guides/ai/LLM_INTELLIGENCE_GUIDE.html) - Advanced Claude API configuration and usage
- [Watch Mode Guide](guides/development/WATCH_MODE_GUIDE.html) - Real-time monitoring deep dive

---

---

## 📦 Asset Manager {#asset-manager}

Install, diff, and update plugin assets directly from the TUI.

**What it covers:**

- Hooks, commands, agents, skills, and rules
- Install/uninstall to any detected `.claude` directory
- Diff installed vs source, bulk install by category, update outdated assets

**Quick start:**

```bash
cortex tui
# Press 'A' for Asset Manager
# i=install, u=uninstall, d=diff, U=update all, I=bulk install, T=target dir
```

**Documentation**: [Asset Manager Guide](guides/asset-manager.html)

---

## 🌿 Worktree Manager {#worktree-manager}

Manage git worktrees from the CLI or the TUI.

**CLI quick start:**

```bash
cortex worktree list
cortex worktree add my-branch --path ../worktrees/my-branch
cortex worktree remove my-branch
cortex worktree prune --dry-run
cortex worktree dir ../worktrees
```

**TUI quick start:**

```bash
cortex tui
# Press 'C' for Worktrees
# Ctrl+N add, Ctrl+O open, Ctrl+W remove, Ctrl+K prune, B set base dir
```

**Documentation**: [Worktree Manager Guide](guides/worktrees.html)

---

## 🤝 Collaboration Flow & Skill Auto-Suggestions {#collaboration}

**New in November 2025** – Inspired by Superpowers and SuperClaude frameworks.

/ctx:brainstorm
    
Supersaiyan-aligned ideation capturing goals, success signals, and solution options.

/ctx:plan
    
Transforms brainstorms into stream-based plans and seeds the Task TUI automatically.

/ctx:execute-plan
    
Locks plans into orchestration view, enforces verification, and syncs tasks.

Skill Auto-Suggester Hook
    
`hooks/skill_auto_suggester.py` reads skills/skill-rules.json and surfaces relevant skills after each prompt.

### Install the skill auto-suggester hook

```bash
cp hooks/skill_auto_suggester.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/skill_auto_suggester.py

# settings.json snippet
{
  "hooks": {
    "user-prompt-submit": [
      {"command": "python3", "args": ["~/.claude/hooks/skill_auto_suggester.py"]}
    ]
  }
}
```

Edit `skills/skill-rules.json` to tweak keyword → `/ctx:*` mappings; no code changes required.

### Recommended workflow

1. `/session:load` – loads context and reminds you to brainstorm.
2. `/ctx:brainstorm` – capture options + constraints.
3. `/ctx:plan` – define workstreams, DoD, verification, and seed tasks.
4. `/ctx:execute-plan` – drive execution via Task TUI + orchestrate view.
5. `/dev:*` commands – build, test, review with quality gate hooks.

See [guides/skills.md](guides/skills.md) for the full catalog and resource snippets.

---

## ℹ AI-Powered Skills & Rating System {#skills-intelligence}

**New in November 2025** – Intelligent skill discovery and community feedback.

→ AI Recommendations
    
Get personalized skill suggestions based on your project type, tech stack, and current task. Confidence scoring and reasoning included.

✓ Rating & Reviews
    
Rate skills 1-5 stars with optional reviews. Track quality metrics, success rates, and community feedback. Anonymous and private.

→ Quality Metrics
    
View aggregated ratings, helpful percentages, task success correlation, usage counts, and token efficiency for every skill.

→ Top Rated Skills
    
Discover highest-rated skills by category. Export ratings data in JSON or CSV for analysis and reporting.

### Quick Start

```bash
# Get AI-recommended skills for your project
cortex skills recommend

# Rate a skill you just used
cortex skills rate owasp-top-10 --stars 5 --review "Essential for security"

# View ratings and reviews
cortex skills ratings owasp-top-10

# See top-rated skills
cortex skills top-rated
```

**Example recommendation output:**

```
=== AI-Recommended Skills ===

Based on project type: python-fastapi
Active context: Building REST API with authentication

1. api-design-patterns (Confidence: 95%)
   Why: FastAPI project with REST API requirements

2. secure-coding-practices (Confidence: 90%)
   Why: Authentication requires security best practices
```

**Documentation**: [Skills Guide](guides/skills.md) - Complete reference including AI recommendations and rating system

---

## Project Structure

```
claude-cortex/
├── commands/           # Slash command definitions (49 across 13 categories)
│   ├── analyze/       # Code analysis, security scanning, troubleshooting
│   ├── cleanup/       # Cleanup and maintenance
│   ├── collaboration/ # Brainstorming, planning, execution
│   ├── deploy/        # Release preparation and deployment
│   ├── design/        # System design and workflow planning
│   ├── dev/           # Development tasks (build, test, review, git, implement)
│   ├── docs/          # Documentation generation and indexing
│   ├── orchestrate/   # Multi-agent task orchestration
│   ├── quality/       # Code quality improvement and cleanup
│   ├── reasoning/     # Dynamic reasoning depth control
│   ├── session/       # Session persistence and reflection
│   ├── test/          # Test generation
│   └── tools/         # Tool selection and optimization
│
├── agents/            # Active specialized agents (28)
│   ├── architect-review.md
│   ├── cloud-architect.md
│   ├── code-reviewer.md
│   ├── component-architect.md
│   ├── context-manager.md
│   ├── database-admin.md
│   ├── database-optimizer.md
│   ├── debugger.md
│   ├── docs-architect.md
│   ├── frontend-optimizer.md
│   ├── javascript-pro.md
│   ├── kubernetes-architect.md
│   ├── memory-keeper.md
│   ├── orchestrator.md
│   ├── performance-monitor.md
│   ├── postgres-expert.md
│   ├── python-pro.md
│   ├── react-specialist.md
│   ├── rest-expert.md
│   ├── rust-pro.md
│   ├── security-auditor.md
│   ├── sql-pro.md
│   ├── state-architect.md
│   ├── tailwind-expert.md
│   ├── test-automator.md
│   ├── typescript-pro.md
│   ├── ui-ux-designer.md
│   ├── vitest-expert.md
│   ├── websocket-engineer.md
│   └── dependencies.map         # Agent dependency graph
│
├── hooks/             # Automation hooks
│
├── rules/             # Reusable rule sets
│   ├── git-rules.md            # Git workflow and commit rules
│   ├── quality-rules.md        # Code organization, failure investigation
│   └── efficiency-rules.md     # Tool optimization, workspace hygiene
│
├── skills/            # Skill packs and metadata (124)
│
├── claude_ctx_py/     # Python CLI implementation
│   ├── cli.py         # CLI entry point
│   ├── core/          # Core management modules
│   ├── init_cmds.py   # Project init helpers
│   └── watch.py       # Watch mode implementation
│
├── schema/            # Validation schemas
├── scripts/           # Helper scripts
│
├── templates/         # Framework configuration templates
│   ├── CLAUDE.md
│   ├── PRINCIPLES.md
│   ├── principles/
│   │   ├── 00-core-directive.md
│   │   ├── 10-philosophy.md
│   │   ├── 20-engineering-mindset.md
│   │   ├── 30-decision-framework.md
│   │   └── 40-quality-philosophy.md
│   ├── RULES.md
│   └── settings.json
├── README.md          # Project overview
└── pyproject.toml     # Python package configuration
```

### Key Capabilities

Turnkey Context Stack
    
Ships with pre-wired agents, rules, and skills so Claude Code starts with a curated context from the first prompt.

Python CLI Included
    
An installable `cortex` CLI mirrors the plugin structure, enabling scripts, CI checks, and local automation.

MCP & Hook Ready
    
Designed to plug in Model Context Protocol servers and command hooks for custom toolchains or compliance gates.

Purple Ops UX
    
Gradients, iconography, and documentation tuned to keep designers, developers, and operators aligned.

---

## Installation

### Via Python Package (Recommended)

```bash
# Install the package (pick one)
pipx install claude-cortex
# or: uv tool install claude-cortex
# or: pip install claude-cortex

# Link assets into ~/.claude
cortex install link

# Install completions and manpages
cortex install post
```

**Manual Usage:**

```bash
# Verify installation
cortex --help

# View documentation
man cortex

# Show current status
cortex status

# Generate dependency map
cortex agent graph --export dependency-map.md
```

**What Gets Installed:**

- Python package (`cortex` command)
- Shell completions (bash/zsh/fish)
- Manpage (`man cortex`)
- Development dependencies (pytest, mypy, black)

For more detailed setup guidance (including shell completion and CLI overrides) see [guides/getting-started.md](guides/getting-started.md).

After adding new CLI subcommands, regenerate shell completions so the new options appear.

---

## Setup & Scope

Keep your local context healthy and consistent across upgrades:

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

# Optional: completions + manpages
cortex install post

# Inspect status in project/global scope
cortex --scope project status
cortex --scope global status
```

---

## Data Directory Overrides

The CLI resolves user/project workspace with:

1. `--scope` / `CORTEX_SCOPE` (`auto`, `project`, `global`) for `.claude/` selection
2. fallback to `~/.claude` when no project-local `.claude/` is found in `auto` mode

Examples:

```bash
# Set explicit scope
export CORTEX_SCOPE=project
cortex status
```

Project-local and explicit directory examples:

```bash
cortex --scope project status
cortex --cortex-root /path/to/claude-cortex status
```

Once exported (for example in `~/.zshrc`), both the CLI and Claude Code share a single source of truth for agents, commands, and workflows.

---

## Core Systems

### 1. Command System

**Location**: `commands/`
**Count**: 49 slash commands across 13 categories

Commands provide curated behavioral prompts for specific development tasks. Each command includes:

- Trigger conditions for automatic activation
- Usage patterns and examples
- MCP integration specifications
- Tool coordination patterns
- Success criteria and boundaries

**Categories**:

- `/analyze` - Code analysis, security, troubleshooting
- `/cleanup` - Cleanup and maintenance
- `/collaboration` - Brainstorming, planning, and execution
- `/deploy` - Release preparation
- `/design` - System design and workflow planning
- `/dev` - Development tasks
- `/docs` - Documentation generation
- `/orchestrate` - Multi-agent orchestration
- `/quality` - Code quality
- `/reasoning` - Reasoning frameworks and structure
- `/session` - Session management
- `/test` - Test generation
- `/tools` - Tool selection

**Reference**: [Command Documentation](guides/commands.md)

---

### 2. Agent System

**Location**: `agents/`
**Active Agents**: 28

Agents are specialized personas with domain expertise and specific capabilities. The system includes:

- **Dependency Management**: `dependencies.map` tracks agent relationships
- **AI Recommendations**: Context-aware agent suggestions via `cortex ai recommend`

**Active Agents**:

- `cloud-architect` - Cloud infrastructure design
- `code-reviewer` - Code quality analysis
- `component-architect` - Component design and architecture
- `context-manager` - Context and session management
- `database-admin` - Database administration and operations
- `database-optimizer` - Database performance optimization
- `debugger` - Issue diagnosis and resolution
- `docs-architect` - Documentation architecture and structure
- `frontend-optimizer` - Frontend performance optimization
- `javascript-pro` - JavaScript expertise
- `kubernetes-architect` - K8s orchestration
- `memory-keeper` - Memory vault curation
- `orchestrator` - High-level planning and delegation
- `performance-monitor` - Performance monitoring and analysis
- `postgres-expert` - PostgreSQL expertise
- `python-pro` - Python expertise
- `react-specialist` - React expertise and best practices
- `rest-expert` - REST API design and implementation
- `rust-pro` - Rust expertise
- `security-auditor` - Security assessment
- `sql-pro` - SQL expertise
- `state-architect` - State management architecture
- `tailwind-expert` - Tailwind CSS expertise
- `test-automator` - Test automation and generation
- `typescript-pro` - TypeScript expertise
- `ui-ux-designer` - UI/UX design and user experience
- `vitest-expert` - Vitest testing framework expertise
- `websocket-engineer` - WebSocket implementation

**Reference**: Agents are defined in `agents/*.md` with YAML front matter.

---

### 3. Rule System

**Location**: `rules/`

Reusable rule sets that define behavioral constraints and best practices.

**Rule Sets**:

- `git-rules.md` - Git workflow and commit rules
- `quality-rules.md` - Code organization, naming conventions, failure investigation
- `efficiency-rules.md` - Tool optimization, parallel operations, workspace hygiene

**Priority System**:

- 🔴 CRITICAL - Security, data safety (never compromise)
- 🟡 IMPORTANT - Quality, maintainability (strong preference)
- 🟢 RECOMMENDED - Optimization, style (apply when practical)

---

### 4. Python CLI

**Location**: `claude_ctx_py/`
**Entry Point**: `cortex`

Python CLI for managing context components outside of Claude Code.

**Capabilities**:

- rule/agent management (list, activate, deactivate)
- AI recommendations, watch mode, and export
- worktree management (list/add/remove/prune/base dir)
- docs, plans, and memory command families
- agent dependency visualization and context export

**Reference**: [CLI Documentation](CLI.md)

---

## Deep Dive Documentation

Comprehensive guides to cortex architecture, optimization strategies, and advanced patterns.

Architecture & Design
    
System architecture, design patterns, and component interactions. Explore dependency injection, progressive disclosure, lazy loading, and extension points.
    →
    
      17KB guide
      Core systems

Skill Recommendation Engine
    
Two-layer recommendation architecture: keyword matching hook + multi-strategy SkillRecommender with semantic, rule-based, and historical signals.
    →
    
      Architecture reference
      28 agents, 124 skills

Agent Skills
    
Progressive disclosure architecture for specialized knowledge. Learn how to create skills, integrate with agents, and keep context lean.
    →
    
      16KB guide
      124 skills

Model Optimization ✓
    
Strategic Haiku vs Sonnet assignment guidance. Hybrid orchestration patterns, decision matrix, and performance benchmarks.
    →
    
      13KB strategy
      Tuning guide

Skills Roadmap →
    
Skill System Intelligence: AI recommendations ✓, ratings & feedback ✓, advanced discovery, analytics, smart bundling, and personalization. Features 1-2 complete.
    →
    
      32KB roadmap
      2/6 features complete

Recent Features ✓
    
Complete implementation of skill composition, semantic versioning, community integration, and effectiveness analytics. Production-ready enterprise features.
    →
    
      32KB reference
      4 features complete

Quality & DevOps
    
Testing infrastructure with 150+ tests, code refactoring, error handling improvements, installation automation, and CI/CD pipeline. Grade improved from B+ to A.
    →
    
      Production ready
      95/100 score

Memory Vault ℹ
    
Persistent knowledge storage for Claude Code sessions. Capture domain knowledge, project context, session summaries, and bug fixes in Markdown format with TUI integration.
    →
    
      4 note types
      Auto-capture

---

## → Technical Architecture Documentation

Comprehensive technical documentation for developers, maintainers, and contributors.

→ Master Architecture
    
Complete system architecture covering all 8 core subsystems: CLI, TUI, AI Intelligence, Memory Vault, Skills, MCP, Component Toggle, and Doctor Diagnostics. The definitive technical reference.
    →
    
      3,700+ lines
      8 subsystems
      v1.1

▶ TUI Architecture
    
Textual framework integration, reactive state management, SPA patterns, command palette, styling system (TCSS), and performance optimization strategies.
    →
    
      963 lines
      Package refactoring

ℹ Memory Vault System
    
3-layer architecture (Interfaces, Memory Module, Storage), 4 note types, auto-capture system, full-text search with relevance scoring, CLI/TUI integration.
    →
    
      1,085 lines
      5 Python modules

→ AI Intelligence System
    
4-layer architecture, pattern learning with collaborative filtering, skill recommendation engine (3 strategies), context detection (6 signals), auto-activation at ≥80% confidence.
    →
    
      1,330 lines
      Machine learning

→ Watch Mode Implementation
    
Real-time monitoring with 2s polling (~1% CPU), git integration, notification system with threshold filtering, auto-activation tracking, resource management.
    →
    
      1,027 lines
      ~20MB memory

✓ Skill Rating & Feedback
    
SQLite storage (3 tables), auto-prompt system (12hr lookback, 24hr cooldown), quality metrics (6 dimensions), TUI integration (Ctrl+R), anonymous hashing.
    →
    
      933 lines
      Privacy-first

→ MCP Server Management
    
Cross-platform server discovery, curated registry (25+ servers, 10 categories), automated installation, configuration validation, TUI browser (Key 7), documentation integration.
    →
    
      1,850 lines
      4 core modules

→ Super Saiyan Mode
    
Enhanced TUI components with smooth animations (CSS transitions), rich styling (semantic color palette), 5 core components, accessibility-first design, performance optimization.
    →
    
      1,254 lines
      < 2% CPU overhead

  → For Developers: These documents provide deep-dive technical details including data models, workflows, performance benchmarks, and development guides. Perfect for onboarding, technical reviews, and system maintenance.

---

## Framework Entry Points

> **Note**: In this repo, core framework files live in `templates/`.
> Copy `templates/CLAUDE.md`, `templates/RULES.md`,
> `templates/settings.json`, plus `templates/principles/` and
> `templates/.active-principles` into `~/.claude/`, then run
> `cortex principles build` to generate `PRINCIPLES.md`.

### CLAUDE.md

Primary framework entry point that loads:

- Core framework (PRINCIPLES.md, RULES.md)
- Workflow rules (automatic for all development tasks)
- Conditional rules (loaded as needed)
- MCP documentation

### PRINCIPLES.md

Generated from `principles/*.md` snippets (tracked in `.active-principles` and ordered by filename).
Use `cortex principles build` to regenerate.

Software engineering principles and philosophy:

- Task-First Approach: Understand → Plan → Execute → Validate
- Evidence-Based Reasoning
- Parallel Thinking
- SOLID principles
- Systems Thinking
- Decision Framework

### RULES.md

Core behavioral rules with priority system:

- Scope Discipline
- Professional Honesty
- Safety Rules
- Temporal Awareness

---

## Configuration Files

### Python Package

**File**: `pyproject.toml`

```toml
[project]
name = "claude-cortex"
version = "0.1.0"
requires-python = ">=3.9"

[project.scripts]
cortex = "claude_ctx_py.cli:main"
```

---

## Development Workflows

### Feature Development

1. Create feature branch (`git checkout -b feature/name`)
2. Use `/design:workflow` to plan implementation
3. Use `/dev:implement` with appropriate persona flags
4. Use `/dev:code-review` for quality validation
5. Use `/test:generate-tests` for test coverage
6. Use `/dev:git` for commit with semantic message
7. Use `/deploy:prepare-release` for deployment preparation

### Bug Fixing

1. Use `/analyze:troubleshoot` for diagnosis
2. Use `/dev:implement` to fix issue
3. Use `/test:generate-tests` for regression coverage
4. Use `/dev:code-review` for validation
5. Use `/dev:git` to commit fix

### Code Quality

1. Use `/analyze:code` for quality assessment
2. Use `/quality:improve` for systematic improvements
3. Use `/quality:cleanup` for dead code removal
4. Use `/dev:code-review` for validation

---

## MCP Integration

The plugin integrates with Model Context Protocol servers for enhanced capabilities:

### Context7

- **Purpose**: Official library documentation lookup
- **Flag**: `--c7` or `--context7`
- **Use For**: Framework patterns, API documentation, version-specific implementations

### Sequential

- **Purpose**: Multi-step reasoning and analysis
- **Flag**: `--seq` or `--sequential`
- **Use For**: Complex debugging, system design, hypothesis testing

### Serena

- **Purpose**: Symbol operations and session persistence
- **Flag**: `--serena`
- **Use For**: Large codebase navigation, project memory, semantic understanding

---

## Best Practices

### Command Usage

1. Use namespace prefixes (`/dev:`, `/test:`, etc.)
2. Specify scope with flags (`--scope file|module|project`)
3. Focus analysis with `--focus` flags
4. Enable validation for critical operations (`--validate`)

### Agent Coordination

1. Let dependency system manage agent activation
2. Use `cortex ai recommend` for context-aware agent suggestions
3. Compose multiple agents for complex tasks
4. Review `dependencies.map` for orchestration patterns

---

## Troubleshooting

### Commands Not Loading

1. Verify assets are linked: `cortex install link --dry-run`
2. Confirm assets are linked: `cortex install link --dry-run`
3. Restart Claude Code
4. Validate command syntax in markdown files

### Agent Not Activating

1. Check agent location (`agents/`)
2. Verify dependencies in `dependencies.map`
3. Use `cortex agent activate <name>` to activate manually
4. Check `cortex ai recommend` for context-based suggestions

### CLI Issues

1. Verify installation: `python3 -m pip show claude-cortex`
2. Check Python version: `python3 --version` (>=3.9 required)
3. Reinstall: `python3 -m pip install --force-reinstall .`

---

## Contributing

### Adding Commands

1. Pick a namespace and command name (e.g., `analyze:code`)
2. Create a markdown file in `commands/` (colon replaced with dash, e.g., `commands/analyze-code.md`)
3. Set `name: "analyze:code"` in front matter
4. Update command count in this index if needed

### Creating Agents

1. Create markdown file in `agents/` with YAML front matter
2. Add dependencies to `dependencies.map`
3. Validate: `cortex agent validate`

---

## References

### Internal Documentation

**Core Documentation**

- [Getting Started](guides/getting-started.html) - Installation and setup
- [Architecture Guide](guides/development/architecture.html) - System design and patterns
- [Command Reference](guides/commands.html) - Complete command catalog

**Skills & Agents**

- [Agent Skills Guide](guides/skills.html) - Progressive disclosure and token optimization
- [Skill Recommendation Engine](architecture/skill-recommendation-engine.html) - Two-layer recommendation architecture
- [Model Optimization](guides/development/model-optimization.html) - Haiku vs Sonnet strategy

**Feature Guides**

- [AI Intelligence Guide](AI_INTELLIGENCE.html) - AI intelligence & automation system overview
- [LLM Intelligence Guide](guides/ai/LLM_INTELLIGENCE_GUIDE.html) - Claude API configuration, pricing, and advanced usage
- [Watch Mode Guide](guides/development/WATCH_MODE_GUIDE.html) - Real-time monitoring and auto-activation
- [Asset Manager Guide](guides/asset-manager.html) - Install, diff, and update assets
- [Worktree Manager Guide](guides/worktrees.html) - Git worktree workflows
- [Docs Viewer Guide](guides/DOCUMENTATION_VIEWER.html) - Browse docs from CLI/TUI
- [Command Palette Guide](guides/COMMAND_PALETTE_GUIDE.html) - Interactive command palette
- [TUI Guide](guides/tui.html) - Terminal user interface
- [TUI Quick Start](guides/tui-quick-start.html) - Get started with TUI in 5 minutes
- [TUI Integration Guide](guides/tui-integration.html) - Integrate TUI into your workflow
- [Skills TUI Integration](guides/skills-tui-integration.html) - Skills system TUI integration
- [TUI Keyboard Reference](guides/tui/tui-keyboard-reference.html) - Complete keyboard shortcuts
- [TUI Navigation](guides/tui/tui-navigation-summary.html) - Navigation patterns

**CLI & Integration**

- [Shell Completions](guides/COMPLETIONS.html) - Bash, Zsh, and Fish completion scripts
- [Warp AI Integration](guides/features/WARP_AI_INTEGRATION.html) - Terminal AI tools integration with context export aliases
- [Prompt Library](guides/prompt-library.html) - On-demand prompts, guidelines, and templates

**Advanced Features**

- [Super Saiyan Mode](features/SUPER_SAIYAN_MODE.html) - Visual excellence framework
- [Kamehameha Overview](features/KAMEHAMEHA_OVERVIEW.html) - Power levels and activation
- [Contextual RAG](features/contextual-rag.html) - Enhanced retrieval with situated context
- [Frontend Aesthetics](features/frontend-aesthetics.html) - Performance-first UI generation
- [Super Saiyan Integration](guides/features/SUPER_SAIYAN_INTEGRATION.html) - Integration guide
- [Parallel Orchestration](guides/development/PARALLEL_ORCHESTRATION_GUIDE.html) - Multi-agent coordination
- [Parallel Workflow Enforcer](guides/development/PARALLEL_WORKFLOW_ENFORCER.html) - Strict parallel execution hook
- [Quality Improvements](guides/development/quality-improvements.html) - Code quality enhancements

### External Resources

- [Claude Code Documentation](https://docs.claude.com/claude-code)
- [Plugin Development Guide](https://docs.claude.com/claude-code/plugins)
- [MCP Specification](https://modelcontextprotocol.io)

---

## Version History

### 2.0.0 (2026-01-08)

- Renamed claude-ctx to cortex across the CLI/TUI, env vars, and docs
- Introduced `CORTEX_ROOT` with a default `~/.cortex` layout and rules sync to `~/.claude/rules/cortex`
- Bundled all plugin assets into the Python package for self-contained installs
- Updated launcher/config flow to prefer `~/.cortex` and bundled asset discovery

### 1.2.0 (2025-12-21)

- Asset Manager TUI for installing, diffing, and updating assets
- Worktree Manager (CLI + TUI) with base directory control
- Installation and linking workflow via `install link` / `install post`
- New modes (Amphetamine, Idea_Lab, Teacher) + mode metadata/conflict detection
- AI stability and context tracking fixes

### 0.1.0 (2025-10-17)

- Initial plugin release
- 34 slash commands across 10 categories
- 11 active agents, 65 total available
- Python CLI for context management
- Complete documentation system

---

## Support

**Repository**: [github.com/NickCrew/claude-cortex](https://github.com/NickCrew/claude-cortex)

**Issues**: [Report a bug or request a feature](https://github.com/NickCrew/claude-cortex/issues)

**Marketplace**: [claude-marketplace](https://github.com/NickCrew/claude-marketplace)

---

*This documentation was generated using `/docs:index` command*
