{"id":47099954,"url":"https://github.com/vibheksoni/quickcontext","last_synced_at":"2026-03-17T20:00:50.790Z","repository":{"id":343832928,"uuid":"1179243114","full_name":"vibheksoni/quickcontext","owner":"vibheksoni","description":"Local code context engine with a Rust parsing/search service and a Python indexing/retrieval engine.","archived":false,"fork":false,"pushed_at":"2026-03-17T00:53:16.000Z","size":1657,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-17T04:22:31.626Z","etag":null,"topics":["code-intelligence","code-search","developer-tools","mcp","python","qdrant","retrieval","rust","semantic-search","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vibheksoni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T20:47:27.000Z","updated_at":"2026-03-17T00:53:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vibheksoni/quickcontext","commit_stats":null,"previous_names":["vibheksoni/quickcontext"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vibheksoni/quickcontext","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2Fquickcontext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2Fquickcontext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2Fquickcontext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2Fquickcontext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vibheksoni","download_url":"https://codeload.github.com/vibheksoni/quickcontext/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibheksoni%2Fquickcontext/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30630010,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T17:32:55.572Z","status":"ssl_error","status_checked_at":"2026-03-17T17:32:38.732Z","response_time":56,"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":["code-intelligence","code-search","developer-tools","mcp","python","qdrant","retrieval","rust","semantic-search","tree-sitter"],"created_at":"2026-03-12T15:14:29.412Z","updated_at":"2026-03-17T20:00:50.752Z","avatar_url":"https://github.com/vibheksoni.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# quickcontext\n\n![quickcontext](assets/QuickContext-banner.png)\n\nquickcontext is a local code context engine for code search, indexing, parsing, and retrieval.\n\nIt currently has two main parts:\n\n- `service/`: a Rust binary for parsing, grep, skeleton generation, text search, protocol search, pattern search, symbol and caller lookup, import graph analysis, and local IPC\n- `engine/`: a Python SDK and CLI for indexing, Qdrant collection management, chunking, deduplication, embeddings, retrieval, watch mode, and edit operations\n\nThe SDK now includes AI-facing retrieval helpers:\n\n- `QuickContext.retrieve_context_auto(...)`\n  Default AI entrypoint. It routes exact symbol questions to the Rust symbol index first, expands behavior-oriented symbol questions with helper symbols from the same implementation file, and falls back to semantic or bundle retrieval for broader natural-language questions.\n- `QuickContext.semantic_search_auto(...)`\n  Lets the SDK choose between fast direct semantic retrieval and the deeper graph-aware bundle path.\n- `QuickContext.semantic_search_bundle(...)`\n  Returns semantic anchors plus distinct semantic neighbor files, related import-graph files, and caller context for deeper codebase exploration.\n\nUse `retrieve_context_auto(...)` as the default for AI workflows, `semantic_search(...)` for direct semantic retrieval, `semantic_search_auto(...)` when you specifically want semantic-only auto-routing, and `semantic_search_bundle(...)` when you explicitly want the deeper cross-file expansion path.\n\n## Status\n\nThis repository is still a work in progress.\n\n- The current focus is the Rust service and Python engine\n- The design can still be improved in many places\n- We want contributors\n- A first-class MCP layer is planned but not part of the tracked repo yet\n\nIf you want to help build it, issues and pull requests are welcome.\n\n## AI Agent Setup\n\nThis repository includes [AI_DOCS.md](AI_DOCS.md) as the clean agent-facing project guide.\n\nIf your coding assistant expects `AGENTS.md` or `CLAUDE.md`, copy `AI_DOCS.md` to the filename your tool expects in your local setup.\n\n## Repository Layout\n\n- `engine/`: Python package and CLI entrypoint\n- `service/`: Rust service and command-line binary\n- `docker-compose.yml`: local Qdrant container\n- `requirements.txt`: Python dependencies\n- `quickcontext.local.example.json`: local config using `fastembed`\n- `quickcontext.example.json`: cloud config using `litellm`\n\n## Platform Support\n\nThe transport layer supports both Windows and Linux.\n\n- Windows transport: named pipe `\\\\.\\pipe\\quickcontext`\n- Linux transport: Unix socket from `QC_SOCKET_PATH`, then `$XDG_RUNTIME_DIR/quickcontext.sock`, then `/tmp/quickcontext-\u003cuser\u003e.sock`\n\nThe request protocol is the same on both platforms: 4-byte little-endian length prefix plus JSON payload.\n\n## Requirements\n\n- Python 3.10 or newer\n- Rust toolchain with Cargo\n- Native C/C++ build toolchain for the tree-sitter grammar crates\n- Docker if you want local Qdrant with `docker compose`\n- Windows or Linux\n\n## Configuration\n\nThe Python CLI resolves configuration in this order:\n\n1. `quickcontext.json` or `.quickcontext.json`\n2. `QC_*` environment variables\n3. built-in defaults from `engine/src/config.py`\n\n### Local config\n\nWindows:\n\n```powershell\nCopy-Item quickcontext.local.example.json quickcontext.json\n```\n\nLinux:\n\n```bash\ncp quickcontext.local.example.json quickcontext.json\n```\n\nThis example uses local Qdrant, `fastembed`, and `llm: null`.\n\nFor that setup, index with `--fast` or `--no-descriptions`.\n\n### Cloud config\n\nWindows:\n\n```powershell\nCopy-Item quickcontext.example.json quickcontext.json\n```\n\nLinux:\n\n```bash\ncp quickcontext.example.json quickcontext.json\n```\n\nThen replace the placeholder API keys before indexing.\n\n### Service path\n\nThe Python layer looks for the service binary at:\n\n- `service/target/release/quickcontext-service.exe`\n- `service/target/release/quickcontext-service`\n\nIf the binary lives somewhere else, set `QC_SERVICE_PATH`.\n\n## Setup\n\n### Windows\n\n```powershell\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npython -m pip install --upgrade pip\npython -m pip install -r requirements.txt\n\ncargo build --release --manifest-path service/Cargo.toml\ndocker compose up -d qdrant\n\nCopy-Item quickcontext.local.example.json quickcontext.json\n\npython -m engine status\npython -m engine init\npython -m engine index . --project quickcontext --fast\n```\n\n### Linux\n\n```bash\nsudo apt-get install -y build-essential\npython3 -m venv .venv\nsource .venv/bin/activate\npython -m pip install --upgrade pip\npython -m pip install -r requirements.txt\n\ncargo build --release --manifest-path service/Cargo.toml\ndocker compose up -d qdrant\n\ncp quickcontext.local.example.json quickcontext.json\n\npython -m engine status\npython -m engine init\npython -m engine index . --project quickcontext --fast\n```\n\n## Running The Rust Service\n\nThe Python layer can auto-start the Rust service if the binary exists at the default path. Running it manually is still the clearest option.\n\nWindows:\n\n```powershell\n.\\service\\target\\release\\quickcontext-service.exe serve\n```\n\nLinux:\n\n```bash\n./service/target/release/quickcontext-service serve\n```\n\n## Common Python CLI Commands\n\n```text\npython -m engine parse .\npython -m engine grep \"CollectionManager\"\npython -m engine skeleton . --markdown\npython -m engine text-search \"auth token\"\npython -m engine protocol-search \"request response\"\npython -m engine pattern-search \"(function_definition name: (identifier) @name)\" --lang python\npython -m engine search \"chunk filter\" --project quickcontext\npython -m engine refresh engine/src/config.py\npython -m engine watch .\npython -m engine list-projects\npython -m engine status\n```\n\n## Validation\n\nUseful validation commands during development:\n\n```text\ncargo check --manifest-path service/Cargo.toml\ncargo test --manifest-path service/Cargo.toml\npython -m py_compile engine/src/pipe.py engine/src/parsing.py engine/src/cli.py engine/__init__.py\nvenv/Scripts/python.exe -m unittest engine.tests.test_regressions\nvenv/Scripts/python.exe scripts/retrieval_benchmark.py --config quickcontext.json --project quickcontext\nvenv/Scripts/python.exe scripts/context_retrieval_benchmark.py --config quickcontext.json --project quickcontext --cases-file scripts/context_retrieval_cases.json --strategy context-auto\nvenv/Scripts/python.exe scripts/symbol_context_benchmark.py --config quickcontext.json --project quickcontext --cases-file scripts/symbol_context_cases.json --strategy context-auto\nvenv/Scripts/python.exe scripts/context_retrieval_benchmark.py --config quickcontext.json --project quickcontext --cases-file scripts/graph_retrieval_cases.json --strategy context-auto\nvenv/Scripts/python.exe scripts/text_retrieval_benchmark.py --config quickcontext.json --cases-file scripts/context_retrieval_cases.json --show-top 3\n```\n\nFor local performance work, keep benchmark notes in `BENCHMARK_LOCAL.md`. That file is intentionally gitignored.\n\n## Contributing\n\nContributors are wanted.\n\nGood areas to help with:\n\n- indexing quality\n- retrieval and ranking\n- protocol extraction quality\n- chunking and deduplication\n- Linux and cross-platform polish\n- future MCP support\n\nIf you want to contribute, start by reading [AI_DOCS.md](AI_DOCS.md).\n\n## License\n\nThis project is licensed under Apache-2.0. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibheksoni%2Fquickcontext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvibheksoni%2Fquickcontext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibheksoni%2Fquickcontext/lists"}