{"id":40273674,"url":"https://github.com/hargabyte/cortex","last_synced_at":"2026-02-23T01:25:56.308Z","repository":{"id":333022752,"uuid":"1134566019","full_name":"hargabyte/cortex","owner":"hargabyte","description":"Code graph tool for AI assistants - understand codebase structure, dependencies, and impact","archived":false,"fork":false,"pushed_at":"2026-02-10T22:14:44.000Z","size":2826,"stargazers_count":18,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-11T01:41:06.257Z","etag":null,"topics":["ai-assistant","cli","code-analysis","developer-tools","golang","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hargabyte.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"hargabyte","thanks_dev":null,"custom":null}},"created_at":"2026-01-14T22:24:10.000Z","updated_at":"2026-02-10T22:14:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hargabyte/cortex","commit_stats":null,"previous_names":["hargabyte/cortex"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/hargabyte/cortex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hargabyte%2Fcortex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hargabyte%2Fcortex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hargabyte%2Fcortex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hargabyte%2Fcortex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hargabyte","download_url":"https://codeload.github.com/hargabyte/cortex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hargabyte%2Fcortex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29734468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T20:09:16.275Z","status":"ssl_error","status_checked_at":"2026-02-22T20:09:13.750Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","cli","code-analysis","developer-tools","golang","static-analysis"],"created_at":"2026-01-20T03:03:08.534Z","updated_at":"2026-02-23T01:25:56.300Z","avatar_url":"https://github.com/hargabyte.png","language":"HTML","funding_links":["https://buymeacoffee.com/hargabyte"],"categories":[],"sub_categories":[],"readme":"# Cortex (cx)\n\n**A codebase intelligence tool that gives AI agents structural understanding of your code.**\n\nCortex builds a dependency graph of your entire codebase and exposes it through a simple CLI and MCP server. Instead of grep-and-hope, your AI assistant gets a map: what calls what, what's important, what breaks if you change something.\n\n## Why Cortex?\n\nAI coding assistants are blind. They can read files, but they can't see structure. When you ask an agent to \"add rate limiting to the API,\" it doesn't know where your API lives, what calls it, or which functions are critical. It spends dozens of tool calls exploring just to figure out where it is.\n\nCortex solves this with a persistent code graph:\n\n| Question | Without Cortex | With Cortex |\n|----------|---------------|-------------|\n| What code relates to this task? | Grep, explore, hope | `cx --smart \"add auth\"` |\n| Is this file safe to edit? | Hope for the best | `cx check file.go` |\n| What breaks if I change this? | No idea | `cx admin impact file.go` |\n| What's the most important code? | Ask the developer | `cx find --keystones` |\n| What's dead code? | Manual audit | `cx find --dead` |\n| Where should I start? | Guess | `cx --map` |\n\n---\n\n## Installation\n\n### Download Binary\n\nGrab the binary for your platform from [GitHub Releases](https://github.com/hargabyte/cortex/releases):\n\n**Linux (amd64):**\n```bash\ncurl -L https://github.com/hargabyte/cortex/releases/latest/download/cx-linux-amd64 -o cx\nchmod +x cx \u0026\u0026 sudo mv cx /usr/local/bin/\n```\n\n**Linux (arm64):**\n```bash\ncurl -L https://github.com/hargabyte/cortex/releases/latest/download/cx-linux-arm64 -o cx\nchmod +x cx \u0026\u0026 sudo mv cx /usr/local/bin/\n```\n\n**macOS (Apple Silicon):**\n```bash\ncurl -L https://github.com/hargabyte/cortex/releases/latest/download/cx-darwin-arm64 -o cx\nchmod +x cx \u0026\u0026 sudo mv cx /usr/local/bin/\n```\n\n**macOS (Intel):**\n```bash\ncurl -L https://github.com/hargabyte/cortex/releases/latest/download/cx-darwin-amd64 -o cx\nchmod +x cx \u0026\u0026 sudo mv cx /usr/local/bin/\n```\n\n**Windows (PowerShell):**\n```powershell\nInvoke-WebRequest -Uri \"https://github.com/hargabyte/cortex/releases/latest/download/cx-windows-amd64.exe\" -OutFile \"cx.exe\"\n# Add the directory containing cx.exe to your PATH\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/hargabyte/cortex.git\ncd cortex\nCGO_ENABLED=1 go build -o cx ./cmd/cx\nsudo mv cx /usr/local/bin/\n```\n\nRequires Go 1.24+ and a C compiler (gcc/clang) for tree-sitter parsing.\n\n---\n\n## Quick Start\n\n```bash\ncd your-project\ncx scan                            # Build the code graph (one-time, ~30 seconds)\ncx --smart \"add authentication\"    # Get task-focused context\ncx find LoginUser                  # Search for entities\ncx check src/auth/handler.go       # Safety check before editing\n```\n\n---\n\n## Commands\n\nCortex has five primary commands that cover everything:\n\n### `cx [target]` — Understand Code\n\nThe bare `cx` command auto-detects what you need based on the argument:\n\n```bash\ncx                                 # Session recovery context\ncx LoginUser                       # Show entity details\ncx src/auth/login.go               # Safety check on a file\ncx --smart \"add rate limiting\"     # Task-focused context assembly\ncx --map                           # Project skeleton overview\ncx --diff                          # Context for uncommitted changes\ncx --trace LoginUser               # Trace call chains\ncx --blame LoginUser               # Entity commit history\n```\n\n**Context flags for `cx`:**\n- `--smart \"task\"` — Hybrid search (semantic + keyword + importance) within a token budget\n- `--diff` — Context for uncommitted git changes\n- `--staged` — Context for staged changes only\n- `--for \u003cfile\u003e` — Full neighborhood context for a specific file\n- `--map` — Project skeleton with function signatures\n- `--budget N` — Token budget (default: 4000)\n- `--depth N` — Max graph hops for `--smart` (default: 2)\n\n### `cx find \u003cpattern\u003e` — Search and Discover\n\n```bash\ncx find Login                      # Name search (prefix match)\ncx find \"auth validation\"          # Full-text concept search\ncx find --semantic \"validate creds\" # Semantic search\ncx find --keystones                # Most important entities (by PageRank)\ncx find --dead                     # Find dead code\ncx find --dead --tier 2            # Include probable dead code\ncx find --dead --tier 3 --chains   # Full analysis with chain grouping\n```\n\n### `cx check [file]` — Quality Gate\n\nUnified quality gate combining safety checks, pre-commit guard, and test selection:\n\n```bash\ncx check src/auth/login.go         # Safety check on a file\ncx check                           # Pre-commit guard (staged files)\ncx check --guard --all             # Guard all modified files\ncx check --test                    # Smart test selection for changes\ncx check --test --gaps             # Coverage gap analysis\ncx check --test --run              # Run the selected tests\ncx check --coverage                # Coverage summary\n```\n\n### `cx scan` — Build the Code Graph\n\n```bash\ncx scan                            # Full scan (first time or rescan)\ncx scan src/auth/                  # Scan specific directory\n```\n\nScans your codebase with tree-sitter, extracts entities (functions, classes, types), builds the dependency graph, computes importance scores, and commits to a versioned database.\n\n### `cx call \u003ctool\u003e` — Machine Gateway\n\nDirect access to all 14 Cortex tools via JSON, designed for programmatic use and MCP pipe mode:\n\n```bash\ncx call --list                              # See all tools with parameter schemas\ncx call context '{\"smart\":\"add auth\",\"budget\":8000}'\ncx call safe '{\"target\":\"src/api/handler.go\"}'\ncx call find '{\"pattern\":\"LoginUser\"}'\ncx call show '{\"name\":\"Store\",\"density\":\"dense\"}'\ncx call map '{}'\n\n# Pipe mode (multiple calls, one process)\necho '{\"tool\":\"cx_find\",\"args\":{\"pattern\":\"Store\"}}' | cx call --pipe\n```\n\n### `cx admin` — Administrative Commands\n\nLess frequently used commands for database management, tagging, and analysis:\n\n```bash\ncx admin db info                   # Database statistics\ncx admin db compact                # Compact the database\ncx admin doctor                    # Health check\ncx admin tag add Entity important  # Tag an entity\ncx admin tag list                  # List all tags\ncx admin sql \"SELECT ...\"          # Direct SQL query\ncx admin blame LoginUser           # Entity commit history\ncx admin history                   # Dolt commit log\ncx admin branch                    # List branches\ncx admin impact file.go            # Blast radius analysis\ncx admin stale                     # Find unchanged entities\n```\n\n\u003e Old commands (`cx show`, `cx safe`, `cx guard`, `cx trace`, etc.) still work for backwards compatibility.\n\n---\n\n## MCP Server — IDE Integration\n\nCortex exposes all its tools through the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), so AI IDEs can query your code graph directly without spawning CLI processes.\n\n### Starting the Server\n\n```bash\ncx serve                           # Start MCP server (all 14 tools)\ncx serve --tools=context,safe,find # Limit to specific tools\ncx serve --list-tools              # Show available tools\n```\n\nOr use the admin namespace:\n```bash\ncx admin serve                     # Same as cx serve\n```\n\n### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `cx_context` | Smart context assembly within a token budget |\n| `cx_safe` | Pre-flight safety check before modifying code |\n| `cx_find` | Search for entities by name pattern |\n| `cx_show` | Show detailed entity information |\n| `cx_map` | Project skeleton overview |\n| `cx_trace` | Trace call chains (callers, callees, paths) |\n| `cx_blame` | Entity commit history |\n| `cx_tag` | Entity tag management |\n| `cx_guard` | Pre-commit quality checks |\n| `cx_test` | Smart test selection and coverage gaps |\n| `cx_dead` | Dead code detection (3 confidence tiers) |\n| `cx_diff` | Changes since last scan |\n| `cx_impact` | Blast radius analysis |\n| `cx_gaps` | Coverage gap analysis |\n\n### IDE Configuration\n\n**Claude Code:**\n\nAdd to `~/.claude/settings.json`:\n```json\n{\n  \"mcpServers\": {\n    \"cortex\": {\n      \"command\": \"cx\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n**Cursor:**\n\nSettings \u003e MCP \u003e Add server:\n```json\n{\n  \"mcpServers\": {\n    \"cortex\": {\n      \"command\": \"cx\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n**Windsurf:**\n\nAdd to `~/.windsurf/mcp.json`:\n```json\n{\n  \"servers\": {\n    \"cortex\": {\n      \"command\": \"cx\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n**VS Code (Copilot):**\n\nAdd to `.vscode/mcp.json` in your project:\n```json\n{\n  \"servers\": {\n    \"cortex\": {\n      \"command\": \"cx\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### Claude Code Session Hook\n\nFor Claude Code users, you can set up a session hook that automatically provides codebase context at the start of each session:\n\n```bash\n# Download the hook script\nmkdir -p ~/bin\ncurl -o ~/bin/cx-session-hook.sh https://raw.githubusercontent.com/hargabyte/cortex/master/scripts/cx-session-hook.sh\nchmod +x ~/bin/cx-session-hook.sh\n```\n\nAdd to `~/.claude/settings.json`:\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [{\n      \"matcher\": \"\",\n      \"hooks\": [{ \"type\": \"command\", \"command\": \"~/bin/cx-session-hook.sh\" }]\n    }]\n  }\n}\n```\n\n---\n\n## How It Works\n\n```\nYour Codebase             Cortex                    AI Agent\n──────────────────────────────────────────────────────────────\n  src/\n  ├── auth/        ──►   cx scan   ──►   .cx/cortex/\n  │   ├── login.go       (tree-sitter    Dolt database:\n  │   └── token.go        parsing)       • entities + signatures\n  ├── api/                    │          • dependency graph\n  │   └── handler.go          │          • importance scores (PageRank)\n  └── ...                     ▼          • version history (Dolt commits)\n                         dolt commit\n                         (auto-versioned)\n```\n\n1. **Scan** — Tree-sitter parses your code into ASTs across 12 languages\n2. **Extract** — Every function, class, type, and interface with full signatures\n3. **Graph** — Dependency edges: who calls whom, who implements what\n4. **Rank** — PageRank identifies which entities are critical\n5. **Version** — Every scan creates a Dolt commit, giving you full change history\n\nThe database lives in `.cx/cortex/` inside your project. Add `.cx/` to your `.gitignore`.\n\n---\n\n## Supported Languages\n\n| Language | Entity Types |\n|----------|-------------|\n| Go | functions, methods, structs, interfaces, constants |\n| TypeScript | functions, classes, methods, interfaces, types, constants |\n| JavaScript | functions, classes, methods, constants |\n| Python | functions, classes, methods, decorators |\n| Java | classes, methods, interfaces, enums, constants |\n| Rust | functions, structs, traits, impl blocks, enums |\n| C | functions, structs, unions, enums, macros |\n| C++ | functions, classes, methods, structs, namespaces |\n| C# | classes, methods, interfaces, structs, records |\n| PHP | classes, methods, interfaces, traits |\n| Kotlin | functions, classes, methods, objects, interfaces |\n| Ruby | classes, modules, methods |\n\n---\n\n## Typical Agent Workflow\n\nHere's how an AI agent uses Cortex during a typical coding task:\n\n```bash\n# 1. Start of session — get oriented\ncx --smart \"add rate limiting to API\" --budget 8000\n\n# 2. Find relevant code\ncx find \"rate limit\"\ncx find --keystones --top 5\n\n# 3. Safety check before editing\ncx check src/api/middleware.go\n\n# 4. After making changes — pre-commit guard\ncx check                           # Guard staged files\ncx check --test                    # Which tests to run?\ncx check --test --run              # Run them\n\n# 5. Rescan after significant changes\ncx scan\n```\n\n---\n\n## Documentation\n\n- [Full Command Reference](docs/commands.md)\n- [MCP Server Setup](docs/mcp-server.md)\n- [Semantic Search](docs/semantic-search.md)\n- [Report Generation](docs/reports.md)\n- [Configuration](docs/configuration.md)\n\n---\n\n## Contributing\n\nIssues and PRs welcome. This tool is actively developed.\n\n---\n\n## License\n\nMIT\n\n---\n\n## Acknowledgments\n\nBuilt with:\n- [tree-sitter](https://tree-sitter.github.io/) — Multi-language parsing\n- [Dolt](https://github.com/dolthub/dolt) — Git-like version control for SQL\n- [MCP](https://modelcontextprotocol.io/) — Model Context Protocol for AI tool integration\n- Inspired by [Beads](https://github.com/steveyegge/beads) by Steve Yegge\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhargabyte%2Fcortex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhargabyte%2Fcortex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhargabyte%2Fcortex/lists"}