Cortex Documentation

Cortex generates a knowledge base for your project that Claude Code reads automatically — before writing a single line of code.

Every time you start a Claude Code session, it knows nothing about your project. You end up re-explaining context: which parts break often, why something was written a certain way, what that refactor from last month was about.

Cortex solves this by analyzing your repository and writing structured context files to .claude/docs/. Claude Code reads these files automatically. The context travels with your code — commit it once and everyone on the team benefits.

Installation

One-line install (recommended)

curl -fsSL https://raw.githubusercontent.com/kovalenko-tech/cortex/main/install.sh | bash

Installs cortex to ~/.local/bin/cortex. Requires Python 3.11+ and git.

With npx

npx @kovalenko-tech/cortex-ai analyze

No installation needed. Node.js checks for Python 3.11+ and installs cortex via pip automatically.

Manual install

pip install git+https://github.com/kovalenko-tech/cortex.git

With security extras

pip install "git+https://github.com/kovalenko-tech/cortex.git#egg=cortex[security]"

Installs bandit for Python security analysis.

Quick Start

cd your-project
cortex setup

cortex analyze

git add .claude/
git commit -m "add cortex context"

// .claude/settings.json
{
  "mcpServers": {
    "cortex": {
      "command": "cortex",
      "args": ["mcp"]
    }
  }
}

How it works

Cortex runs four analysis passes on your repository and combines the results into per-file context documents.

1. Git History Mining

For every source file, Cortex reads the full git log and extracts bug fixes, refactors, and the commit messages that explain why things changed.

2. Co-change Analysis

Builds a matrix of which files changed together across all commits. If auth.py and session.py changed together in 80% of commits, they're marked as related.

3. Static Analysis

Parses each file's AST to extract functions, classes, imports, and which test files cover the module.

4. Security Scan

Runs SAST tools (bandit for Python, semgrep for others) per file and scans git history for accidentally committed secrets.

Results are combined into .claude/docs/src/auth.py.md — one file per source file. Claude Code reads these before making changes.

Context files

Cortex writes all context to .claude/docs/ in your project root. The structure mirrors your source tree:

Per-file context format

Each .md file follows this structure:

Git History Mining

Cortex reads your entire git log and extracts structured insights per file. It classifies commits by type and links each insight to the file it affected.

Commit classification

Commits are classified using keyword patterns:

Only bug_fix and refactor commits appear in Historical Insights — feature commits are noise.

Co-change analysis

Cortex builds a co-change matrix from all commits. If files A and B changed together in many commits, they're listed as related. This reveals implicit coupling that isn't visible in imports.

# Co-change score formula
score = co_changes / min(changes_A, changes_B)
# score > 0.2 → files are related

Risk Scoring

Every file gets a risk score from 0 to 100 based on four factors:

Risk levels

HIGH Score ≥ 50 — handle with care, check tests, review changes carefully

MEDIUM Score 25–49 — some risk factors present

LOW Score < 25 — safe to modify

Viewing risk

cortex risks              # all files sorted by risk score
cortex risks --level HIGH # only high-risk files

Freshness Tracking

Context files show when they were generated and how many commits happened since. This tells Claude Code whether to trust the context.

Freshness levels

⚡ FRESH Analyzed < 3 days ago and ≤ 2 commits since

⚠️ STALE Analyzed 3–14 days ago or 3–10 commits since

❌ OUTDATED Analyzed 14+ days ago or 10+ commits since

Checking freshness

cortex freshness              # all files
cortex freshness --stale-only # only problem files

Keeping context fresh

cortex install-hook            # auto-update on every commit
cortex watch                   # auto-update when commits arrive
cortex analyze --since HEAD~10 # refresh last 10 commits worth of files

Security Audit

Cortex runs SAST analysis per file and scans git history for leaked secrets. Results appear in each file's context and in .claude/docs/SECURITY_REPORT.md.

What's scanned

• SQL injection, XSS, command injection
• Hardcoded secrets (API keys, passwords, tokens)
• Dangerous functions (eval, exec, pickle.loads)
• Secrets in git history (GitHub tokens, OpenAI keys, AWS credentials)
• Weak cryptography (MD5/SHA1 for passwords)

Tools used

cortex security # audit only, no full analysis
cortex analyze  # security runs as part of full analysis

Dependency Scan

Checks your project dependencies for known vulnerabilities. Results written to .claude/docs/DEPENDENCIES.md.

cortex deps

PR Knowledge Mining

The most unique feature of Cortex. It mines merged GitHub PRs for implicit architectural decisions — the reasoning that lives in review comments but never makes it into code.

Setup

export GITHUB_TOKEN=ghp_...
cortex mine-prs
cortex analyze   # context now includes PR decisions

What it extracts

Cortex scans PR comments for these patterns:

Output in context

Saved data

Mined knowledge is saved to .claude/pr-knowledge.json. Run cortex analyze after cortex mine-prs to include it in context files.

AI Summaries

When ANTHROPIC_API_KEY is set, Cortex uses Claude Haiku to write a 2–3 sentence technical overview for each file. All other features work without an API key.

export ANTHROPIC_API_KEY=sk-ant-...
cortex analyze

The summary appears in the Overview section of each context file and describes what the file does, its main responsibility, and any notable risk areas.

MCP Server

Cortex can run as an MCP (Model Context Protocol) server, allowing Claude Code to query context directly without reading .md files manually.

Configuration

Add to .claude/settings.json in your project:

{
  "mcpServers": {
    "cortex": {
      "command": "cortex",
      "args": ["mcp"]
    }
  }
}

Restart Claude Code. The MCP server exposes two tools:

Commands

Setup & Analysis

Inspect

Maintenance

Integration

Flags

Claude Code Integration

There are two ways to use Cortex with Claude Code:

Option A: MCP Server (automatic)

Claude Code queries Cortex directly when it needs context. No manual steps required.

// .claude/settings.json
{
  "mcpServers": {
    "cortex": {
      "command": "cortex",
      "args": ["mcp"]
    }
  }
}

Option B: Manual context (explicit)

Add to your CLAUDE.md:

## Project Context

Before editing any file, run:
```bash
python .claude/get_context.py <file_path>
```

Claude Code will run this command and read the output before making changes.

GitHub Actions

Auto-update context on every push to keep it fresh for the whole team.

# .github/workflows/cortex.yml
name: Update Cortex Context

on:
  push:
    branches: [main, master]

jobs:
  cortex:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install git+https://github.com/kovalenko-tech/cortex.git
      - run: cortex analyze --no-llm
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "docs: update cortex context [ci]"
          file_pattern: ".claude/**"

Git Pre-commit Hook

Automatically update context for modified files before each commit.

cortex install-hook

This installs a pre-commit hook at .git/hooks/pre-commit that runs cortex analyze --since HEAD on staged files and adds the updated context to the commit.

Use Case: Solo Developer

You work on a project alone and use Claude Code regularly. The problem: every session starts fresh and you spend the first few minutes re-explaining what the project does.

Setup (one time)

cd your-project
cortex setup        # analyze + MCP config + git hook
git add .claude/ CLAUDE.md
git commit -m "add cortex context"

Daily workflow

The pre-commit hook keeps context fresh automatically. When you open Claude Code, it has full context. No extra steps.

When to run manually

cortex risks     # check before a big refactor
cortex freshness # if you haven't committed in a while
cortex deps      # before a release

Use Case: Team Workflow

Multiple developers work on the same codebase. You want everyone's Claude Code to have the same context without each person running analysis.

Setup with GitHub Actions

Set up the GitHub Action to auto-update context on every merge to main. The .claude/docs/ directory is committed to the repo — everyone gets it when they pull.

PR knowledge mining

Run cortex mine-prs periodically to capture team decisions from PR discussions. Commit .claude/pr-knowledge.json alongside the context files.

export GITHUB_TOKEN=ghp_...
cortex mine-prs
cortex analyze
git add .claude/
git commit -m "update cortex context + PR knowledge"

Use Case: Onboarding New Developers

A new developer joins the team and needs to understand the codebase. Normally this takes days of reading code and asking questions.

With Cortex

If .claude/docs/ is committed to the repo, the new developer clones it and immediately has:

• Which parts of the codebase have a bug history
• Which files are high-risk and should be approached carefully
• Why certain architectural decisions were made (from PR knowledge)
• Which files have no tests
• Security issues to be aware of

Tip: generate CLAUDE.md first

cortex init

This generates a CLAUDE.md with project overview, key directories, build and test commands. Claude Code reads this first — useful for humans too.

Use Case: Code Review

Before reviewing a PR or making changes to a risky file, get the full context first.

Before reviewing a file

cortex context src/auth.py

Shows historical bugs, risk score, PR decisions, and security notes for that specific file.

Before merging a branch

cortex diff main # update context for changed files only
cortex risks     # see if any HIGH risk files were modified

After a large refactor

cortex analyze --no-cache # full re-analysis with updated risk scores