{"id":48874868,"url":"https://github.com/iliaal/codesage","last_synced_at":"2026-04-16T00:01:29.371Z","repository":{"id":351629687,"uuid":"1211816061","full_name":"iliaal/codesage","owner":"iliaal","description":"Code intelligence engine for AI coding agents. Structural graph queries plus semantic search, exposed via CLI and MCP.","archived":false,"fork":false,"pushed_at":"2026-04-15T20:15:25.000Z","size":466,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-15T21:27:02.752Z","etag":null,"topics":["ai-agents","code-intelligence","code-search","embeddings","mcp","rust","semantic-search","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"C","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/iliaal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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}},"created_at":"2026-04-15T19:22:21.000Z","updated_at":"2026-04-15T20:15:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iliaal/codesage","commit_stats":null,"previous_names":["iliaal/codesage"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/iliaal/codesage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iliaal%2Fcodesage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iliaal%2Fcodesage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iliaal%2Fcodesage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iliaal%2Fcodesage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iliaal","download_url":"https://codeload.github.com/iliaal/codesage/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iliaal%2Fcodesage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31865078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"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-agents","code-intelligence","code-search","embeddings","mcp","rust","semantic-search","tree-sitter"],"created_at":"2026-04-16T00:01:18.566Z","updated_at":"2026-04-16T00:01:29.365Z","avatar_url":"https://github.com/iliaal.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodeSage\n\n[![CI](https://github.com/iliaal/codesage/actions/workflows/ci.yml/badge.svg)](https://github.com/iliaal/codesage/actions/workflows/ci.yml)\n[![Tests](https://github.com/iliaal/codesage/actions/workflows/tests.yml/badge.svg)](https://github.com/iliaal/codesage/actions/workflows/tests.yml)\n[![Secret scan](https://github.com/iliaal/codesage/actions/workflows/secret-scan.yml/badge.svg)](https://github.com/iliaal/codesage/actions/workflows/secret-scan.yml)\n[![Version](https://img.shields.io/github/v/release/iliaal/codesage)](https://github.com/iliaal/codesage/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Follow @iliaa](https://img.shields.io/badge/Follow-@iliaa-000000?style=flat\u0026logo=x\u0026logoColor=white)](https://x.com/intent/follow?screen_name=iliaa)\n\nCodeSage is a code intelligence engine for AI coding agents. It combines structural graph queries (symbols, references, dependencies) and semantic search (embedding retrieval with cross-encoder reranking) in a single Rust binary, usable as a CLI or over MCP.\n\n## What you can do with it\n\n- Find code by natural-language query: \"where does auth happen?\", \"error handling in the GC\".\n- Look up symbol definitions by name across a codebase.\n- Trace imports, calls, and inheritance for any symbol.\n- Map import and include relationships between files.\n- Estimate which files a change breaks (change impact analysis).\n- Build curated code bundles for LLM consumption in JSON, markdown, or flat-text (gitingest-style) form.\n- Read per-file git history: churn, fix ratio, historical co-change, risk score.\n- Expose all of the above over MCP so Claude Code, Codex, or Cursor can call them.\n\n## Supported languages\n\nPHP, Python, C, Rust, JavaScript, TypeScript.\n\n## Getting started\n\n```bash\n# Build with GPU support\ncargo build --release -p codesage --features cuda\n\n# Initialize and index a project\ncd /path/to/your/project\ncodesage init\ncodesage index\n\n# Search\ncodesage search \"authentication handler\"\ncodesage search --json --limit 20 \"database connection pooling\"\n\n# Structural queries\ncodesage find-symbol MyClass\ncodesage find-references some_function --kind call\ncodesage dependencies src/main.py\n\n# Change impact analysis (who breaks if you touch this?)\ncodesage impact DocumentRepository --depth 2 --source-only\ncodesage impact src/auth/session.ts --json\n\n# Context bundle for LLM consumption\ncodesage export \"authentication flow\" --limit 5 --callers\ncodesage export MyClass --symbol --format md\ncodesage export \"auth flow\" --format ingest    # gitingest-style flat-text bundle\n\n# Git history: churn, fix ratio, co-change, risk score\ncodesage git-index                                          # initial populate; hooks keep it fresh\ncodesage git-index --full                                   # force full rescan (weekly hygiene)\ncodesage coupling src/auth/session.ts --limit 5             # files that historically change with this\ncodesage risk src/auth/session.ts                           # score with decomposition\n\n# MCP server for Claude Code / Codex / Cursor (one global server, every onboarded project)\nclaude mcp add --scope user codesage -- codesage mcp\n\n# Auto-reindex on git operations\ncodesage install-hooks\n\n# Diagnose installation\ncodesage doctor\n```\n\n## Recipes\n\nCommon pipelines using `codesage` with `git`. Each is one shell line plus what the output tells you.\n\n### Risk check before committing\n\n```bash\ngit diff --cached --name-only | codesage risk-diff\n```\n\nPipes the staged file list through `assess_risk_diff`. Output shows the max risk score, files in each risk bucket (hotspot, fix-heavy, test-gap, wide blast radius), and paste-ready summary notes for the commit message or PR description. If `max_score \u003e= 0.6` or any `test_gap_files` appear, consider adding tests, splitting the patch, or flagging concerns.\n\n### Tests to run after editing\n\n```bash\ngit diff --cached --name-only | codesage tests-for\n```\n\nReturns sibling tests (resolved by language convention) plus tests that historically change with the edited files (from co-change history). Replaces \"I'll run all tests\" with a focused list.\n\n### Audit a feature branch before opening a PR\n\n```bash\ngit diff origin/main...HEAD --name-only | codesage risk-diff\n```\n\nSame as the pre-commit check, but scoped to everything on the branch instead of just the staged diff. Useful as the last step before `gh pr create`.\n\n### What changed in the last week, ranked by risk\n\n```bash\ngit log --since='1 week ago' --name-only --pretty='' | sort -u | codesage risk-diff --json | jq '.files[] | select(.score \u003e= 0.5) | .file'\n```\n\nLists high-risk files touched in recent history. Good signal during a retrospective or a \"where should we focus refactoring?\" discussion.\n\n### Trifecta for one file\n\n```bash\ncodesage risk path/to/file.rs\ncodesage tests-for path/to/file.rs\ncodesage coupling path/to/file.rs --limit 5\n```\n\nWhen you're about to dive into one specific file. Risk score, suggested tests, and what historically co-changes — together they calibrate caution before you start editing.\n\n## Claude Code plugin\n\n`plugins/codesage-tools/` wraps everything above into one command per task. The marketplace manifest lives at the repo root.\n\n```bash\nclaude plugin marketplace add /path/to/codesage\nclaude plugin install codesage-tools@codesage\n/codesage-onboard /path/to/project\n```\n\nSlash commands: `/codesage-onboard`, `/codesage-reset`, `/codesage-reindex`, `/codesage-bench`, `/codesage-eval`. The plugin handles global MCP registration, per-project init, indexing, git hook install (Husky-aware), and writes a `.claude/CLAUDE.md` hint teaching the agent how to route MCP calls.\n\n## Indexing pipeline\n\n`codesage index` walks the project, parses every supported file, extracts structural data and embeddings, and writes both into the same SQLite database.\n\n```mermaid\nflowchart LR\n    A[Project files] --\u003e B[Discover\u003cbr/\u003ewalk + excludes]\n    B --\u003e C[Tree-sitter parse]\n    C --\u003e D[Extract symbols\u003cbr/\u003eand references]\n    C --\u003e E[Chunk text\u003cbr/\u003erecursive splitter]\n    D --\u003e F[(SQLite\u003cbr/\u003efiles, symbols, refs)]\n    E --\u003e G[Embed via ONNX\u003cbr/\u003eMiniLM-L6-v2]\n    G --\u003e H[(sqlite-vec\u003cbr/\u003echunks_minilm_384)]\n```\n\nParsing happens in parallel via Rayon; SQLite writes are batched. Re-running `codesage index` is incremental: only files whose content hash changed are re-parsed and re-embedded.\n\n## Search pipeline\n\nA query flows through five stages:\n\n```mermaid\nflowchart LR\n    Q[Query string] --\u003e E[Embed\u003cbr/\u003eMiniLM-L6-v2]\n    E --\u003e K[KNN retrieval\u003cbr/\u003esqlite-vec\u003cbr/\u003eoverfetch 5x]\n    K --\u003e B[Symbol boost\u003cbr/\u003e+0.1 per token match]\n    B --\u003e R[Cross-encoder rerank\u003cbr/\u003ems-marco\u003cbr/\u003eblend 50/50]\n    R --\u003e A[Symbol annotation]\n    A --\u003e T[Top-N results]\n```\n\n1. Embed the query with MiniLM-L6-v2 (22M params, 384d) via ONNX Runtime.\n2. Prepend file path and symbol context to chunks before embedding.\n3. Boost chunks whose content matches known symbol names.\n4. Re-score the top candidates with ms-marco-MiniLM-L6-v2 and blend 50/50 with the semantic score.\n5. Annotate each result with overlapping function and class names.\n\nThe reranker is optional. Set or remove it in `config.toml`; stages 1-3 and the annotation still run without it.\n\n## Configuration\n\n`codesage init` generates `.codesage/config.toml`:\n\n```toml\n[project]\nname = \"my-project\"\n\n[embedding]\nmodel = \"sentence-transformers/all-MiniLM-L6-v2\"\ndevice = \"gpu\"                                        # \"gpu\" or \"cpu\"\nreranker = \"cross-encoder/ms-marco-MiniLM-L6-v2\"     # optional, remove to disable\n\n[index]\nexclude_patterns = [\n  \"**/tests/**\", \"**/vendor/**\", \"**/node_modules/**\",\n  \"**/*.test.ts\", \"**/*Test.php\", \"**/*.phpt\",\n]\n```\n\nModels download from HuggingFace the first time you use them.\n\n## Architecture\n\nA Rust workspace with six crates:\n\n```mermaid\nflowchart TD\n    cli[cli\u003cbr/\u003ebinary + MCP server]\n    gr[graph\u003cbr/\u003eindexing + query pipeline]\n    parser[parser\u003cbr/\u003etree-sitter + discovery]\n    storage[storage\u003cbr/\u003eSQLite + sqlite-vec + FTS5]\n    embed[embed\u003cbr/\u003eONNX + reranker + chunking]\n    protocol[protocol\u003cbr/\u003eshared types]\n\n    cli --\u003e gr\n    gr --\u003e parser\n    gr --\u003e storage\n    gr --\u003e embed\n    parser --\u003e protocol\n    storage --\u003e protocol\n    embed --\u003e protocol\n    gr --\u003e protocol\n```\n\n| Crate | Role |\n|-------|------|\n| `protocol` | Shared types (Symbol, Reference, SearchResult) |\n| `parser` | File discovery, tree-sitter parsing, symbol and reference extraction |\n| `storage` | SQLite with sqlite-vec KNN and FTS5 |\n| `embed` | ONNX embedding inference, cross-encoder reranking, chunking |\n| `graph` | Indexing orchestration and search pipeline |\n| `cli` | Binary with CLI subcommands and MCP server |\n\nStorage is a single SQLite database per project at `.codesage/index.db`: structural tables (symbols, refs, files) plus model-specific vector tables for embeddings.\n\n## Retrieval benchmarks\n\n`bench/` holds the harness:\n\n- `codesage-bench-runner` runs a YAML corpus of ground-truth cases through `codesage search` and reports miss rate, median first-hit, recall@5, and recall@10.\n- `extract-eval-cases.py` mines eval cases from Claude Code session transcripts and git commit history.\n\nCorpora aren't bundled. Bring your own, or point the plugin at `$CODESAGE_BENCH_CORPUS_DIR`.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). In short: file an issue first, add a test, update `CHANGELOG.md` under `[Unreleased]` for user-visible changes.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filiaal%2Fcodesage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filiaal%2Fcodesage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filiaal%2Fcodesage/lists"}