Cortex
Give AI coding agents the right context from your repository.
Cortex builds a local map of your code, symbols, relationships, and project rules. Coding agents query that map through the CLI instead of guessing or reading the whole repository.
Your code stays on your machine. MCP is not required.
Start
Requires Node.js 20.9+ and Git.
npm install --global @danielblomma/cortex-mcp
cd your-project
cortex init --bootstrap
This indexes the repository, adds Cortex instructions to AGENTS.md, installs
Git hooks, and starts the background watcher.
Check the setup:
cortex doctor
Use
# Find relevant code.
cortex search "where is authentication handled?" --json
# Follow relationships from a search result.
cortex related <entity-id> --json
# See what a change may affect.
cortex impact "authentication" --json
# Read repository rules.
cortex rules --json
# Compare a changed file with nearby patterns.
cortex pattern-evidence src/auth.ts --json
# Inspect deterministic active conventions for a file or indexed entity.
cortex conventions src/payments/retry.ts --json
# Get cited, deterministic context before implementing a code task.
cortex guidance src/payments/retry.ts --task "add bounded retry handling" --json
# Review the staged, unstaged, and non-ignored untracked candidate against HEAD.
cortex review --diff --json
# Refresh context after significant changes.
cortex update
Agents can run these commands directly. cortex init adds instructions that
tell them to search before answering and check impact before refactoring. They
do not need an MCP connection.
What Cortex adds
Without Cortex, an agent often searches by filename and reads many unrelated files. Cortex gives it structured repository context:
- semantic search across code, rules, and architecture decisions;
- symbol definitions and file relationships;
- caller and dependency traversal;
- impact analysis before refactoring;
- active rules, deprecations, and source-of-truth signals;
- deterministic, subsystem-scoped convention profiles with cited reusable symbols;
- incremental updates after Git and filesystem changes.
The pipeline is local and straightforward:
repository -> local index -> Cortex CLI -> coding agent
Commands you will use
Run cortex help for the complete command list.
cortex conventions uses only the local index. It returns bounded, live-backed
version-1 profiles and does not call a model, planner, provider, or network
service. See Repository convention profiles
for the exact eligibility, limit, hashing, persistence, and safety contract.
Before implementing a code task, use cortex guidance as cited additive
context—not policy authority. Continue to use normal search, related, and
impact when needed, and never skip explicit active rules or conflicts. The
command is local-only and inspection-only; see the exact versioned contract in
Pre-coding guidance.
After coding and before finalization, use cortex review --diff. It separates
exact source-of-truth violations from heuristic local-pattern warnings and is
inspection-only. See Deterministic diff review.
Keep the index fresh
Git hooks and the watcher normally update Cortex automatically.
cortex status
cortex watch status
cortex update
Run cortex update manually after a large change or when results look stale.
Large repositories
Make lexical and graph search available first while semantic indexing continues in the background:
cortex bootstrap --background --profile interactive
cortex indexing status --json
This mode supports macOS, Linux, and WSL. Native Windows should use normal foreground bootstrap.
Upgrade
npm install --global @danielblomma/cortex-mcp@latest
cortex init --force
cortex bootstrap
cortex update
Project configuration and rules are preserved. See CHANGELOG.md for version-specific notes.
Optional MCP compatibility
The normal Cortex workflow uses the CLI. If a client explicitly requires MCP,
run cortex connect.
DeepSeek Harness integration
Cortex supports DeepSeek Harness through the V1 explicit tools and skills
integration. Cortex 2.6.0 contains and validates the integration source against
the pinned Harness 0.1.1-rc.2 release. Separate npm bundle distribution is
deferred and currently unavailable.
The bundle provides four agent-scoped tools (cortex_search,
cortex_related, cortex_impact, and cortex_rules) and five Cortex behavior
skills (change-impact, context-review, pattern-review, repo-research,
and using-cortex). Retrieval is local, repository-scoped, explicit, and
user-controlled. The integration does not automatically initialize, update,
or watch a repository.
V2 proactive/assistive retrieval remains planned and experimental; it is not included in Cortex 2.6.0. See the V1-to-V2 integration plan for details.
Links
License
MIT