GitHub - benogoulart/Cortex: The brain behind your coding agent.

Developer intelligence for your codebase. Scans, indexes and understands your project — so coding agents like OpenCode get the right context every time.

Preview · Features · Quick Start · Commands · Architecture · Structure · Roadmap · License

cortex indexes your codebase into a structured knowledge graph — files, symbols, dependencies, architecture — and exposes it through a CLI that coding agents can query. Instead of re-explaining your project to every agent session, you cortex init once and the context is always there.

Preview

❯ cortex init

  Scanning C:\my-project...

  cortex initialized

  Files:      142
  Lines:      18.400
  TypeScript: 98
  JavaScript: 12
  JSON:       32

  Index saved to .cortex/index.json

❯ cortex analyze

  PROJECT ANALYSIS
  ────────────────────────────────────────

  Name:       my-project
  Analyzed:   18/08/2026, 22:00:00
  Version:    1.0.0

  STATS
  ────────────────────────────────────────
  Files:      142
  Lines:      18.400
  TypeScript: 98
  JavaScript: 12
  JSON:       32

  ARCHITECTURE
  ────────────────────────────────────────
  src                  89 ██████████████
  tests                24 █████
  config               12 ███
  scripts               8 ██
  docs                  6 █
  ...

  DEPENDENCY HEALTH
  ────────────────────────────────────────
  Total edges:     156
  Cycles:          0
  Critical path:   12 files

❯ cortex search "auth"

  Search: "auth"
  ────────────────────────────────────────

  src/auth/AuthService.ts (38) █████████████
    ✦ class      AuthService
    ✦ function   validate
    ✦ function   refreshToken

  src/auth/AuthController.ts (25) █████████
    ✦ function   login
    ✦ function   callback

  src/middleware/auth.ts (18) ███████
    ✦ function   authenticate

❯ cortex context "authentication"

  CONTEXT: "authentication"
  ────────────────────────────────────────

  Relevant files:

  → src/auth/AuthService.ts (relevance: 38, impact: 12)
    ✦ class      AuthService
    ✦ function   validate
    ✦ function   refreshToken
    Dependencies: src/auth/UserRepository.ts
    Dependents: src/api/routes.ts, src/app/page.tsx
    Transitive deps: 5 total

  → src/auth/AuthController.ts (relevance: 25, impact: 8)
    ✦ function   login
    ✦ function   callback

  → src/middleware/auth.ts (relevance: 18, impact: 3)
    ✦ function   authenticate

❯ cortex remember "Controllers must never access repositories directly"

  Memory saved
  ────────────────────────────────────────
  Category:   convention
  ID:         mem_1a2b3c
  Created:    19/08/2026, 15:30:00

❯ cortex memory search "database"

  MEMORY: "database"
  ────────────────────────────────────────

  [convention] mem_1a2b3c — 19/08/2026
    Controllers must never access repositories directly

  [pattern] mem_4d5e6f — 18/08/2026
    Use Repository pattern for all database access

  [decision] mem_7g8h9i — 17/08/2026
    PostgreSQL with Prisma as ORM

❯ cortex plan "add payment system"

  Add Payment System
  ────────────────────────────────────────
  Plan for: add payment system. 3 module(s) affected (1 high-impact).
  Risk: H HIGH
  Complexity: 42/100
  Tasks: 14

  Risk factors:
    - 1 high-impact module(s) affected
    - Wide scope: 3 modules affected

  Affected modules:
    src/billing [high]
      Contains relevant symbols: BillingService, createInvoice
      symbols: BillingService, createInvoice
    src/api [medium]
      Imports relevant modules: ./billing
    src/models [low]
      Contains relevant symbols: Invoice

  ? DISCOVERY
  ────────────────────────────────────────
    [ ] !! Understand current state of src/billing
        files: src/billing
    [ ] ! Understand current state of src/api
        files: src/api
    [ ] ! Review existing patterns for: BillingService, createInvoice, Invoice

  A ARCHITECTURE
  ────────────────────────────────────────
    [ ] !! Define module boundaries and interfaces
        files: src/billing
    [ ] ! Define data flow and dependencies
        files: src/billing, src/api, src/models
    [ ] ! Design API contracts and service boundaries

  I IMPLEMENTATION
  ────────────────────────────────────────
    [ ] ! Implement BillingService in src/billing
        files: src/billing
    [ ] . Implement createInvoice in src/billing
        files: src/billing

  T TESTING
  ────────────────────────────────────────
    [ ] !! Add tests for src/billing
        files: src/billing
    [ ] ! Add integration tests for cross-module interactions
        files: src/billing, src/api, src/models
    [ ] !!! Verify existing tests still pass

❯ cortex report

  CORTEX REPORT
  ════════════════════════════════════════════
  Overall Score: [G] 82/100
  Files: 142 | Findings: 7 (C:1 W:3 I:3)

  [G] ARCHITECT — 90/100
  ────────────────────────────────────────
  Analyzed 142 files across 5 layers. Found 0 cycles, 2 layer violations.

  [Y] REVIEWER — 75/100
  ────────────────────────────────────────
  Reviewed 12 changed files. 3 warnings, 1 critical.

  [G] SECURITY — 85/100
  ────────────────────────────────────────
  Scanned 142 files. Found 2 security issues (risk: 15/100).

  [Y] TESTER — 78/100
  ────────────────────────────────────────
  Test coverage: 45 fully tested, 12 partial, 85 untested.

  TOP ACTIONS
  ────────────────────────────────────────
    [X] secret src/config/env.ts:5
      Hardcoded API key detected
      → Use environment variables or a secrets manager
    [!] coverage src/services/payment.ts
      8 symbols with no test coverage
      → Add tests for: processPayment, validateCard, refund

Features

Feature	Description
Codebase indexing	Scans your project and builds a structured index of files, symbols and dependencies
Tree-sitter AST	Proper AST parsing for accurate symbol extraction (classes, functions, types, enums)
Symbol extraction	Detects classes, functions, interfaces, types, enums, constants — exported and private
Dependency graph	Maps which files import what, with cycle detection and impact scoring
Architecture analysis	Shows directory structure, entry points and project composition
Semantic search	Multi-factor weighted scoring: path, symbol, import, export, structural relevance
Context engine	Get all relevant files, symbols, dependency chains and impact scores for a topic
Dependency analysis	Cycle detection, transitive deps, critical path, impact scoring
Project memory	Persistent decisions, conventions, patterns and mistakes per project
Task planner	Transform vague tasks into structured execution plans with risk assessment
Unified report	Cross-agent correlation, per-file findings, prioritized actions, overall health score
Configuration	Persist include/ignore, layer definitions, security patterns, search weights in `.cortex/config.json`
Plan persistence	Save and retrieve execution plans over time
Run history	Track report snapshots and compare health trends
Multi-language	TypeScript, JavaScript (ESM + CJS), JSON — extensible to more
Fast	Indexes thousands of files in seconds with tree-sitter
Zero config	Works out of the box — just `cortex init` in any project
Agent-ready	Structured output designed for MCP integration with OpenCode
Tested	38 tests across graph, search, memory, and planner modules

Quick Start

Install

# Clone and link globally
git clone https://github.com/benogoulart/Cortex.git
cd cortex
pnpm install
pnpm build
pnpm link --global

Use in any project

cd my-project
cortex init              # scan and create .cortex/index.json
cortex analyze           # see project insights
cortex search "auth"     # find relevant code
cortex context "payment" # get full context for a topic
cortex report            # unified analysis across all agents
cortex remember "use repository pattern"  # save a convention
cortex memory search "pattern"            # recall knowledge
cortex plan "add payment system"          # generate execution plan
cortex history reports   # view past report snapshots
cortex setup            # configure MCP for OpenCode, Claude Code or Codex

Commands

Command	Description
`cortex init`	Scan codebase and create the index at `.cortex/index.json`
`cortex analyze`	Show project stats, architecture, dependency health and top symbols
`cortex status`	Show index metadata (version, last analysis, file count)
`cortex search <query>`	Search files and symbols by semantic relevance score
`cortex context <topic>`	Get all relevant files, symbols, dependency chains and impact scores
`cortex remember <text>`	Save a decision, convention, pattern or mistake to project memory
`cortex memory`	List all memory entries
`cortex memory search <query>`	Search through project memory
`cortex memory show <id>`	Show a specific memory entry
`cortex memory delete <id>`	Delete a memory entry
`cortex plan <description>`	Generate a structured execution plan from a task description
`cortex review`	Review git diff for architecture, security and test issues
`cortex agent <name>`	Run a specialized analysis agent (architect, reviewer, security, tester, all)
`cortex report`	Run all agents and show unified report with cross-agent correlation
`cortex history reports`	List past report snapshots
`cortex history plans`	List saved execution plans
`cortex setup`	Configure MCP server for OpenCode, Claude Code or Codex in this project

Options

Flag	Description	Default
`-r, --root <path>`	Project root directory	`process.cwd()`
`-a, --agent <agents>`	Agent(s) to configure: opencode, claude, codex, all	`all`
`-i, --include <patterns>`	File glob patterns to include	`*/`
`--ignore <patterns>`	Additional patterns to ignore	—
`-n, --limit <number>`	Max results for search	`15`
`--verbose`	Show score breakdown (search)	—
`-d, --depth <number>`	Transitive dependency depth (context)	`3`
`-c, --category <type>`	Memory category (remember)	auto-detect
`-j, --json`	Output as JSON	—
`--save`	Save plan/report to `.cortex/`	—

Memory Categories

Category	Description
`decision`	Architectural or technical decisions made in the project
`convention`	Coding conventions and style rules
`pattern`	Reusable patterns and idioms used
`mistake`	Known pitfalls and things to avoid
`task`	Pending or tracked tasks
`note`	General notes about the project

Examples

# Analyze a specific project
cortex init --root /path/to/project

# Search for specific symbols
cortex search "useEffect"

# Get context before starting work
cortex context "database migration"

# Save important decisions
cortex remember -c decision "Use PostgreSQL with Prisma ORM"

# Save conventions
cortex remember "All API responses must follow { data, error } format"

# Save patterns
cortex remember -c pattern "Use repository pattern for database access"

# Save things to avoid
cortex remember -c mistake "Never use setTimeout for debouncing — use lodash.debounce"

# Recall knowledge
cortex memory search "database"
cortex memory search "convention"

MCP Setup

Cortex exposes 21 tools via MCP so coding agents can query your codebase automatically. Supports OpenCode, Claude Code, and Codex.

Quick setup

cd my-project
cortex setup                          # auto-detect agents, configure all
cortex setup --agent opencode         # OpenCode only
cortex setup --agent claude           # Claude Code only
cortex setup --agent codex            # Codex only
cortex setup --agent opencode,claude  # multiple agents

Manual setup

OpenCode — opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cortex": {
      "type": "local",
      "command": ["cortex-mcp"]
    }
  }
}

Claude Code — .mcp.json

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

Codex — .codex/config.toml

[mcp_servers.cortex]
command = "cortex-mcp"
args = []

Available MCP tools

Tool	Description
`cortex_init`	Index the project
`cortex_status`	Show index stats
`cortex_analyze`	Dependency analysis
`cortex_search`	Semantic search
`cortex_context`	Dependency context
`cortex_remember`	Save memory
`cortex_memory_search`	Search memory
`cortex_memory_list`	List memory
`cortex_memory_get`	Get memory entry
`cortex_memory_delete`	Delete memory
`cortex_plan`	Generate execution plan
`cortex_review`	Review git diff
`cortex_dependencies`	File dependencies
`cortex_agent_architect`	Architecture analysis
`cortex_agent_reviewer`	Enhanced code review
`cortex_agent_security`	Security analysis
`cortex_agent_tester`	Test strategy
`cortex_agent_all`	Run all agents
`cortex_report`	Unified report
`cortex_history`	Report/plan history
`cortex_config_get`	Read configuration

Architecture

graph TD
    CLI["cortex CLI"] --> Core["@cortex/core"]

    subgraph Core["@cortex/core"]
        Indexer["indexer — file discovery"]
        Parser["parser — tree-sitter AST"]
        Symbols["symbols — code intelligence"]
        Graph["graph — dependency mapping"]
        Search["search — semantic scoring"]
        Memory["memory — project knowledge"]
        Planner["planner — task planning"]
        Report["report — unified analysis"]
        Config["config — project settings"]
        PlanStore["plan-store — saved plans"]
        History["history — run snapshots"]
    end

    Indexer --> |fast-glob| Files[("Codebase")]
    Parser --> |tree-sitter| AST["AST nodes"]
    AST --> Symbols
    Files --> Symbols
    Symbols --> Index[(".cortex/index.json")]
    Files --> Graph
    Graph --> Index
    Search --> |weighted scoring| Results["Search Results"]
    Memory --> |persistent| MemoryStore[(".cortex/memory.json")]
    Planner --> |risk + phases| Plans["Execution Plans"]
    Report --> |all agents| UnifiedReport["Unified Report"]
    Config --> |settings| ConfigStore[(".cortex/config.json")]
    PlanStore --> |save/load| Plans
    History --> |snapshots| RunHistory[(".cortex/history/")]

    CLI --> |init| Indexer
    CLI --> |analyze| Index
    CLI --> |search| Search
    CLI --> |context| Graph
    CLI --> |remember| Memory
    CLI --> |memory| Memory
    CLI --> |plan| Planner
    CLI --> |report| Report
    CLI --> |history| History

    OpenCode["OpenCode Agent"] --> |MCP| MCP["MCP Server"]
    MCP --> |tool calls| Core
    Agents --> |analyze| Core
    Agents --> |architect| Graph
    Agents --> |reviewer| Review
    Agents --> |security| Files
    Agents --> |tester| Graph

How it works:

cortex init walks your project with fast-glob, reads every source file, parses symbols with tree-sitter AST, builds a dependency graph from imports, and writes everything to .cortex/index.json.
cortex analyze reads the index and produces a dashboard: file counts, language breakdown, directory architecture, entry points, dependency health (cycles, critical path) and the most important symbols.
cortex search scores every file and symbol against your query using multi-factor weighted scoring: path relevance, symbol name matching, import context, export prominence, and structural importance.
cortex context goes deeper: it finds relevant files, resolves their full dependency graph (direct, transitive, dependents), computes impact scores, and returns a complete picture of the code area with cycle warnings.
cortex remember saves project knowledge (decisions, conventions, patterns, mistakes) to .cortex/memory.json. Auto-detects category from text or accepts --category flag.
cortex memory searches and retrieves stored knowledge, enabling agents to recall project context across sessions.
cortex plan takes a task description, analyzes the codebase to find affected modules, assesses risk, and generates a phased execution plan with discovery, architecture, implementation, testing, and security tasks.
cortex review parses git diff output and checks for architecture violations, security issues (hardcoded secrets, XSS, SQL injection), missing tests for new functions, complexity increases, and code quality problems.
MCP Server exposes all Cortex capabilities as MCP tools over stdio. Any MCP-compatible host (OpenCode, Claude Code, VS Code) can connect and invoke tools like cortex_search, cortex_context, cortex_review, etc.
Agents are specialized deep-analysis modules. The architect agent detects layer violations and coupling issues. The reviewer agent performs graph-aware, convention-aware code review. The security agent runs full-file scans with OWASP mapping. The tester agent maps test coverage and suggests missing tests. Each agent is available via CLI (cortex agent <name>), MCP, or as a core library function.
Unified Report (cortex report) runs all agents, correlates findings across agents, groups them per-file, and produces a single health score with a prioritized action list. Reports can be saved to .cortex/history/ for trend tracking over time.
Configuration (.cortex/config.json) persists project settings — file patterns, layer definitions, custom security patterns, search weights, and review rules — across sessions.

Data model

The index stores everything in a single JSON file:

{
  "version": "1.0.0",
  "project": {
    "name": "my-project",
    "root": "/path/to/project",
    "analyzedAt": "2026-08-19T15:00:00.000Z",
    "stats": {
      "totalFiles": 142,
      "totalLines": 18400,
      "languages": { "typescript": 98, "javascript": 12, "json": 32 }
    }
  },
  "files": [
    {
      "path": "src/auth/AuthService.ts",
      "relativePath": "src/auth/AuthService.ts",
      "language": "typescript",
      "lines": 245,
      "symbols": [
        { "name": "AuthService", "kind": "class", "line": 12, "endLine": 80, "exported": true, "signature": "class AuthService" },
        { "name": "validate", "kind": "function", "line": 34, "endLine": 42, "exported": true, "signature": "async validate(token: string): Promise<boolean>" }
      ],
      "imports": ["./UserRepository", "../middleware/auth"],
      "exports": ["AuthService"]
    }
  ],
  "graph": {
    "edges": [
      { "from": "src/auth/AuthService.ts", "to": "src/auth/UserRepository.ts", "type": "import" }
    ]
  }
}

Memory is stored separately:

{
  "version": "0.3.0",
  "entries": [
    {
      "id": "mem_1a2b3c",
      "text": "Controllers must never access repositories directly",
      "category": "convention",
      "tags": ["architecture", "controllers", "repositories"],
      "createdAt": "2026-08-19T15:30:00.000Z",
      "context": ["src/controllers/", "src/repositories/"]
    }
  ]
}

Tech Stack

Component	Technology
Language	TypeScript 5 (ESM)
Runtime	Node.js 22+
Package manager	pnpm 9 (workspaces)
File discovery	fast-glob
Build	tsup
CLI framework	commander
Testing	vitest
Parsing	tree-sitter (TypeScript, JavaScript)
MCP	@modelcontextprotocol/server v2

Project Structure

cortex/
├── packages/
│   ├── core/                     # Core library — indexing, parsing, analysis
│   │   └── src/
│   │       ├── types/            # Shared TypeScript types
│   │       ├── indexer/          # File discovery with fast-glob
│   │       ├── parser/           # AST extraction (tree-sitter + regex fallback)
│   │       ├── symbols/          # Symbol detection (classes, functions, etc.)
│   │       ├── graph/            # Dependency graph with cycle detection
│   │       ├── search/           # Semantic search with weighted scoring
│   │       ├── memory/           # Persistent project knowledge
│   │       ├── planner/          # Task planning and risk assessment
│   │       ├── review/           # Git diff analysis and code review
│   │       ├── agents/           # Specialized analysis agents
│   │       │   ├── architect.ts  # Architecture analysis
│   │       │   ├── reviewer.ts   # Enhanced code review
│   │       │   ├── security.ts   # Security analysis
│   │       │   ├── tester.ts     # Test strategy
│   │       │   └── index.ts      # Agent registry
│   │       ├── report/           # Unified cross-agent report
│   │       ├── config/           # Project configuration (.cortex/config.json)
│   │       ├── plan-store/       # Plan persistence
│   │       └── history/          # Report snapshots and trends
│   │
│   ├── cli/                      # CLI interface
│   │   └── src/
│   │       ├── commands/
│   │       │   ├── init.ts       # cortex init
│   │       │   ├── analyze.ts    # cortex analyze
│   │       │   ├── status.ts     # cortex status
│   │       │   ├── search.ts     # cortex search
│   │       │   ├── context.ts    # cortex context
│   │       │   ├── remember.ts   # cortex remember
│   │       │   ├── memory.ts     # cortex memory
│   │       │   ├── plan.ts       # cortex plan
│   │       │   ├── review.ts     # cortex review
│   │       │   ├── agent.ts      # cortex agent <name>
│   │       │   ├── report.ts     # cortex report
│   │       │   └── history.ts    # cortex history
│   │       └── index.ts          # CLI entry point (commander)
│   │
│   └── mcp/                      # MCP Server — exposes tools via stdio
│       └── src/
│           └── index.ts          # McpServer with 21 tools
│
├── .gitignore
├── package.json                  # Monorepo root
├── pnpm-workspace.yaml           # Workspace config
├── tsconfig.json                 # Shared TypeScript config
├── vitest.config.ts              # Test config
├── CHANGELOG.md                  # Auto-generated changelog
├── logo.png                      # Project logo
├── wordmark.png                  # Wordmark
└── README.md

Roadmap

All milestones completed. Current version: v1.0 — Complete Developer Intelligence Layer.

Version	Milestone	Status
~~v0.1~~	Foundation	Done
~~v0.2~~	Context Engine	Done
~~v0.3~~	Memory	Done
~~v0.4~~	Task Planner	Done
~~v0.5~~	Code Review	Done
~~v0.6~~	MCP Server	Done
~~v0.7~~	Agents	Done
v1.0	Unified	Current

Contributing

Issues and pull requests are welcome. The project is a monorepo managed with pnpm workspaces — run pnpm install at the root to set up everything.

pnpm dev          # watch mode for all packages
pnpm build        # build all packages
pnpm test         # run test suite
pnpm lint         # type-check with tsc --noEmit

License

MIT — use it, fork it, index it.

Built with TypeScript · Node.js · pnpm · tree-sitter · fast-glob · commander

Navigation Menu

Repository files navigation

Preview

Features

Quick Start

Install

Use in any project

Commands

Options

Memory Categories

Examples

MCP Setup

Quick setup

Manual setup

Available MCP tools

Architecture

Data model

Tech Stack

Project Structure

Roadmap

Contributing

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.codex		.codex
packages		packages
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
cortex		cortex
logo.png		logo.png
package.json		package.json
pnpm		pnpm
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
wordmark.png		wordmark.png

Latest commit

History

Folders and files

Repository files navigation

Preview

Features

Quick Start

Install

Use in any project

Commands

Options

Memory Categories

Examples

MCP Setup

Quick setup

Manual setup

Available MCP tools

Architecture

Data model

Tech Stack

Project Structure

Roadmap

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages