{"id":50614380,"url":"https://github.com/philipjohnbasile/callsieve","last_synced_at":"2026-06-08T09:01:15.455Z","repository":{"id":362315704,"uuid":"1256488941","full_name":"PhilipJohnBasile/callsieve","owner":"PhilipJohnBasile","description":"Stop paying AI coding agents to grep your repo. CallSieve is a local-first, deterministic retrieval layer that feeds agents compact context packets to cut token spend — no cloud, no API key, 20+ agents and MCP clients.","archived":false,"fork":false,"pushed_at":"2026-06-06T18:29:00.000Z","size":964,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T08:19:43.944Z","etag":null,"topics":["ai","cli","code-search","coding-agents","developer-tools","llm","local-first","mcp","retrieval","rust","token-optimization"],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/PhilipJohnBasile.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":null,"governance":null,"roadmap":"ROADMAP.md","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-06-01T20:33:52.000Z","updated_at":"2026-06-06T18:29:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/PhilipJohnBasile/callsieve","commit_stats":null,"previous_names":["philipjohnbasile/callsieve"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/PhilipJohnBasile/callsieve","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipJohnBasile%2Fcallsieve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipJohnBasile%2Fcallsieve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipJohnBasile%2Fcallsieve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipJohnBasile%2Fcallsieve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhilipJohnBasile","download_url":"https://codeload.github.com/PhilipJohnBasile/callsieve/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipJohnBasile%2Fcallsieve/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34055249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","cli","code-search","coding-agents","developer-tools","llm","local-first","mcp","retrieval","rust","token-optimization"],"created_at":"2026-06-06T07:01:39.866Z","updated_at":"2026-06-08T09:01:15.318Z","avatar_url":"https://github.com/PhilipJohnBasile.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CallSieve\n\nCallSieve is the local codebase filter for AI coding agents.\n\nIt indexes a repository and returns compact, structured context so agents can spend fewer tokens on blind grep, file discovery, repeated reads, and rediscovering project structure.\n\nRetrieval itself spends zero AI model tokens: CallSieve ranks against a local index before the prompt exists. The returned context packet still consumes agent context tokens when read, so every packet is compact by default.\n\n## Product Promise\n\nStop paying AI agents to grep your repo.\n\nCallSieve is not another coding agent. It is the context and retrieval layer underneath coding agents.\n\n## Competitive Posture\n\nCallSieve is built to stay slim while making the strongest practical token-saving case:\n\n- Slimmest architecture: Rust CLI, local `.callsieve/index.json`, deterministic ranking, no cloud service, no API key, no vector database, and no web dashboard.\n- Best agent-agnostic setup story: Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity CLI, Cursor, VS Code, Windsurf, Continue, Zed, Junie, JetBrains AI Assistant, Amp, Goose, Warp, Cline, Zoo Code, Roo, and generic stdio MCP clients.\n- Strongest proof posture: `benchmark`, `eval-retrieval`, `trace-check`, `trace-replay`, `pilot-*`, `proof-report`, `enterprise-proof-report`, and `evidence-pack`.\n- Strongest token-saving positioning: read these files first, grep only if needed. CallSieve retrieval costs zero AI model tokens; the compact packet is the only token-bearing artifact agents need to read first.\n\n## How CallSieve Compares\n\nAs of June 2026, CallSieve is best compared as retrieval infrastructure, not as a replacement coding assistant.\n\n| Category | Examples | How CallSieve compares |\n| --- | --- | --- |\n| AI coding IDEs | Cursor, Windsurf, Continue | These bundle chat, edits, autocomplete, and context indexing. CallSieve is narrower: local deterministic retrieval, MCP, hooks, and compact context packets. It is stronger for portability and auditability, but weaker on polished IDE UX and semantic search. |\n| Agent CLIs | Claude Code, Codex CLI, Aider | Claude Code and Codex are full agents that read, edit, run commands, and search files. CallSieve sits in front of them as a context-first tool. Aider is the closest technical peer because its repo map gives LLMs compact codebase structure, but Aider is still an editing agent. |\n| Enterprise code intelligence | Sourcegraph Cody and Sourcegraph Search | Sourcegraph is broader: enterprise search, code graph, IDE and web experiences, and multi-repo context. CallSieve is slimmer: local CLI, local JSON index, no cloud, no API key, no vector DB, and no dashboard. |\n| Semantic RAG and code indexers | Embedding or vector-backed codebase tools | These can be better for vague semantic discovery. CallSieve is more deterministic, explainable, local-first, and proof-oriented, but it can miss queries that need semantic matching beyond symbols, paths, imports, tests, and keywords. |\n\nThe wedge is agent-agnostic setup plus local proof: CallSieve can make Codex, Claude Code, GitHub Copilot, Cursor, Windsurf, Continue, or any MCP client read the right files first, then audit whether that happened. It wins when a team wants a vendor-neutral context layer across many agents. It loses when the buyer only wants one integrated AI editor.\n\n## Open Source And Commercial Model\n\nCallSieve's core local engine is open source under the [MIT License](LICENSE).\n\nThe public repo includes the local CLI, MCP server, repository indexer, deterministic retrieval, agent-context workflow, benchmark harness, proof reports, docs, and tests. The commercial motion is not selling access to the code. It is selling outcomes around it: paid pilots, local installation, agent integration, evidence collection, retrieval tuning, private workflow support, and enterprise proof reporting.\n\nFor proposed commercial packages and placeholder pricing, see [commercial/PRICING.md](commercial/PRICING.md).\n\nKeep broad claims gated. Use `context_payload_reduction` for estimated prompt-payload savings, and use observed token reduction only when real paired transcripts provide audited token counts.\n\n## Current State\n\nCallSieve is now an open-source local Rust CLI with a JSON index, deterministic retrieval, optional local embeddings, optional LSP reference enrichment, CODEOWNERS and git-history signals, stack-trace-aware error context, lifecycle hooks for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity CLI, and Cline, MCP/rule/template setup for Cursor, VS Code, Windsurf, Continue, Zed, Junie, JetBrains AI Assistant, Amp, Goose, Warp, and Zoo Code, context-first guardrails, daemon/watch freshness support, benchmark reports, observed-session traces, and gated proof reports.\n\nPublic hybrid A/B result: on the 50-issue SWE-bench Lite subset in `benchmarks/public/manifest-50.json`, lexical and opt-in hybrid retrieval both scored `56.0%` first-correct-file@5 (`+0.0 pp`, 0 wins, 0 losses, 50 ties) in the refreshed June 6, 2026 current-head run. The 30-issue natural-language slice in `benchmarks/public/manifest-nl.json` also stayed flat at `20.0%` lexical and `20.0%` hybrid (`+0.0 pp`, 1 win, 1 loss, 28 ties). Hybrid is proven wired and non-regressing here, not quality-lifting. The reports also show hybrid above naive grep on both slices: `+50.0 pp` on the 50-issue set and `+6.7 pp` on the natural-language slice.\n\nFor human installation and client setup, see [docs/INSTALL.md](docs/INSTALL.md). For AI CLI and wrapper behavior, see [docs/AGENT_CLI.md](docs/AGENT_CLI.md). For observed whole-session proof collection, see [docs/OBSERVED_SESSIONS.md](docs/OBSERVED_SESSIONS.md). For dogfooding and less-grep measurement, see [docs/DOGFOOD.md](docs/DOGFOOD.md). For paid pilot packaging, see [docs/PILOTS.md](docs/PILOTS.md).\n\nThe core workflow is:\n\n```text\nindex repo -\u003e ask for agent context -\u003e read returned files first -\u003e grep only if needed -\u003e audit traces and savings\n```\n\n## Try It In 60 Seconds\n\n```bash\ncargo install --git https://github.com/PhilipJohnBasile/callsieve\ncallsieve demo /path/to/repo --task \"find where login is handled\"\ncallsieve hook install /path/to/repo --client generic --strict --force\ncallsieve hook doctor /path/to/repo\ncallsieve codex-hooks install /path/to/repo --strict --force\ncallsieve claude-hooks install /path/to/repo --strict --force\n```\n\n`demo` proves the retrieval loop without configuring an agent. `hook install` creates repo-local launchers and search shims under `.callsieve/` so testers can start an agent with CallSieve-first guardrails without changing global PATH or shell profiles. Hook-capable clients also get local project hooks or plugins that inject CallSieve context and block pre-context broad search after they are trusted.\n\n`agent-context` defaults to a budgeted `skim` packet: compact file, symbol, reason, related-test, and risk hints with no snippets. Output includes `retrieval_cost.retrieval_model_tokens = 0` so agents can distinguish zero-token local retrieval from the context tokens spent reading the returned packet. Use `--profile normal`, `--profile full`, `--snippets-per-file`, or the focused `focus`, `related`, and `tests` commands to reveal more detail only after the first packet is insufficient.\n\nOptional retrieval signals stay opt-in:\n\n```bash\ncargo build --features embed\ntarget/debug/callsieve index \u003crepo\u003e --embeddings\ntarget/debug/callsieve agent-context \u003crepo\u003e \"\u003ctask\u003e\" --embeddings --git-boost\ntarget/debug/callsieve agent-context \u003crepo\u003e \"\u003ctask\u003e\" --error \u003cstacktrace.log\u003e\n```\n\n`--embeddings` requires a binary built with `--features embed`; the default build stays deterministic and dependency-light. `--git-boost` nudges recently changed or high-churn files only when requested. `--error` parses stack traces and error logs, then promotes indexed files named in the frames. The integer displayed score remains lexical and explainable; hybrid retrieval only changes ordering when explicitly enabled.\n\nJSON output is compact by default for agent token savings. Add global `--pretty` for human-readable formatting.\n\n## Current CLI Surface\n\n```bash\ncallsieve index \u003cpath\u003e [--lsp] [--embeddings]\ncallsieve symbols \u003cpath\u003e\ncallsieve symbol \u003cpath\u003e \u003csymbol_name\u003e\ncallsieve query \u003cpath\u003e \"\u003cquestion\u003e\" [--why-debug]\ncallsieve context \u003cpath\u003e \"\u003ctask\u003e\" [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--no-snippets] [--profile skim|normal|full] [--token-budget \u003cn\u003e] [--why-debug] [--format json|markdown]\ncallsieve agent-context \u003cpath\u003e \"\u003ctask\u003e\" [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--profile skim|normal|full] [--token-budget \u003cn\u003e] [--why-debug] [--embeddings] [--error \u003cfile\u003e] [--git-boost] [--format json|markdown]\ncallsieve focus \u003cpath\u003e --file \u003cfile\u003e [--symbol \u003csymbol\u003e]\ncallsieve related \u003cpath\u003e --file \u003cfile\u003e\ncallsieve tests \u003cpath\u003e --file \u003cfile\u003e\ncallsieve demo \u003cpath\u003e [--task \"\u003ctask\u003e\"] [--lsp]\ncallsieve memory-clear \u003cpath\u003e\ncallsieve benchmark \u003cpath\u003e \"\u003ctask\u003e\" [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--no-snippets] [--profile skim|normal|full] [--token-budget \u003cn\u003e]\ncallsieve benchmark-suite \u003cpath\u003e \u003ctasks.json\u003e [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--no-snippets] [--profile skim|normal|full] [--token-budget \u003cn\u003e]\ncallsieve bench-public \u003cmanifest.json\u003e \u003crepos_dir\u003e [--k \u003cn\u003e] [--out \u003cpath\u003e] [--embeddings] [--compare]\ncallsieve bench-run \u003cmanifest.json\u003e --workdir \u003cdir\u003e [--compare] [--k \u003cn\u003e] [--limit \u003cn\u003e] [--out \u003cpath\u003e] [--resume]\ncallsieve eval-retrieval \u003cmanifest.json\u003e [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--no-snippets] [--profile skim|normal|full] [--token-budget \u003cn\u003e] [--json]\ncallsieve perf-report \u003cpath\u003e [--tasks \u003cmanifest.json\u003e] [--iterations \u003cn\u003e] [--json]\ncallsieve trace-summary \u003ctrace.json\u003e\ncallsieve session-start \u003cpath\u003e \"\u003ctask\u003e\" --client codex --model \u003cname\u003e --trace \u003ctrace.json\u003e [--expected-file \u003cpath\u003e] [--critical-file \u003cpath\u003e]\ncallsieve session-event \u003ctrace.json\u003e --command \u003ccmd\u003e [--files-read \u003cpath\u003e...] [--context-selected-file \u003cpath\u003e...] [--tokens \u003cn\u003e] [--phase baseline|callsieve]\ncallsieve session-finish \u003ctrace.json\u003e --out \u003csummary.json\u003e\ncallsieve trace-replay \u003cpath\u003e \u003ctasks.json\u003e \u003ctrace.json\u003e [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--no-snippets]\ncallsieve trace-check \u003ctrace.json\u003e [--strict]\ncallsieve benchmark-report \u003cmanifest.json\u003e [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--no-snippets]\ncallsieve benchmark-doctor \u003cmanifest.json\u003e\ncallsieve pilot-init \u003cmanifest.json\u003e [--sessions \u003cn\u003e]\ncallsieve pilot-task add \u003cmanifest.json\u003e \u003crepo\u003e \"\u003ctask\u003e\" [--id \u003cid\u003e] [--expected-file \u003cpath\u003e] [--critical-file \u003cpath\u003e] [--external] [--pair-id \u003cid\u003e] [--task-category \u003cname\u003e] [--difficulty \u003cname\u003e] [--condition \u003cname\u003e] [--token-source transcript_context_tokens]\ncallsieve pilot-task reject \u003cmanifest.json\u003e --task-id \u003cid\u003e --reason \u003creason\u003e\ncallsieve pilot-run \u003cmanifest.json\u003e --task-id \u003cid\u003e --mode baseline|callsieve --command \u003ccmd\u003e [--files-read \u003cpath\u003e...] --tokens \u003cn\u003e\ncallsieve pilot-collect-ollama \u003cmanifest.json\u003e [--model qwen2.5-coder:7b] [--limit \u003cn\u003e] [--context-limit \u003cn\u003e]\ncallsieve pilot-collect-lm-studio \u003cmanifest.json\u003e [--model qwen3-coder-next] [--base-url http://127.0.0.1:1234/v1] [--limit \u003cn\u003e] [--context-limit \u003cn\u003e]\ncallsieve pilot-qa \u003cmanifest.json\u003e\ncallsieve pilot-finalize \u003cmanifest.json\u003e --out \u003cproof.json\u003e\ncallsieve pilot-report \u003cmanifest.json\u003e [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--no-snippets]\ncallsieve proof-report \u003cmanifest.json\u003e [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--no-snippets]\ncallsieve enterprise-proof-report \u003cmanifest.json\u003e [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--no-snippets]\ncallsieve pilot-doctor \u003cmanifest.json\u003e\ncallsieve evidence-pack \u003cmanifest.json\u003e [--anonymize]\ncallsieve policy-check \u003ctrace.json\u003e [--strict]\ncallsieve mcp\ncallsieve mcp-config \u003cpath\u003e [--format json|toml]\ncallsieve mcp-registry-manifest [--out \u003cserver.json\u003e]\ncallsieve status \u003cpath\u003e\ncallsieve daemon \u003cpath\u003e [--background] [--foreground] [--once] [--lsp]\ncallsieve daemon-status \u003cpath\u003e\ncallsieve daemon-stop \u003cpath\u003e\ncallsieve watch \u003cpath\u003e [--debounce-ms \u003cn\u003e] [--foreground] [--lsp]\ncallsieve agent-setup \u003cpath\u003e --client \u003ccodex|claude|copilot|opencode|antigravity|cursor|vscode|windsurf|continue|zed|junie|jetbrains|amp|goose|warp|cline|zoo|roo|generic\u003e [--force]\ncallsieve setup-agent \u003ccodex|claude|copilot|opencode|antigravity|cursor|vscode|windsurf|continue|zed|junie|jetbrains|amp|goose|warp|cline|zoo|roo|generic\u003e \u003cpath\u003e [--force]\ncallsieve bootstrap \u003cpath\u003e --client \u003ccodex|claude|copilot|opencode|antigravity|cursor|vscode|windsurf|continue|zed|junie|jetbrains|amp|goose|warp|cline|zoo|roo|generic\u003e [--strict] [--force] [--lsp]\ncallsieve doctor \u003cpath\u003e --client \u003ccodex|claude|copilot|opencode|antigravity|cursor|vscode|windsurf|continue|zed|junie|jetbrains|amp|goose|warp|cline|zoo|roo|generic\u003e [--fix] [--strict]\ncallsieve codex-bootstrap \u003cpath\u003e --model \u003cname\u003e [--force]\ncallsieve codex-hooks install \u003cpath\u003e [--strict] [--force] [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--lsp]\ncallsieve codex-hooks doctor \u003cpath\u003e [--strict] [--smoke] [--fix]\ncallsieve codex-hooks trust-ack \u003cpath\u003e\ncallsieve codex-hooks uninstall \u003cpath\u003e\ncallsieve claude-hooks install \u003cpath\u003e [--strict] [--force] [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--lsp]\ncallsieve claude-hooks doctor \u003cpath\u003e [--strict]\ncallsieve claude-hooks uninstall \u003cpath\u003e\ncallsieve copilot-hooks|opencode-hooks|antigravity-hooks|cline-hooks install \u003cpath\u003e [--strict] [--force] [--limit \u003cn\u003e] [--snippets-per-file \u003cn\u003e] [--lsp]\ncallsieve copilot-hooks|opencode-hooks|antigravity-hooks|cline-hooks doctor \u003cpath\u003e [--strict]\ncallsieve copilot-hooks|opencode-hooks|antigravity-hooks|cline-hooks uninstall \u003cpath\u003e\ncallsieve editor-hook \u003cpath\u003e --editor \u003cvscode|cursor|generic\u003e [--force]\ncallsieve hook install \u003cpath\u003e --client \u003ccodex|claude|copilot|opencode|antigravity|cursor|vscode|windsurf|continue|zed|junie|jetbrains|amp|goose|warp|cline|zoo|roo|generic\u003e [--strict] [--force] [--lsp]\ncallsieve hook doctor \u003cpath\u003e\ncallsieve hook uninstall \u003cpath\u003e\ncallsieve guard \u003cpath\u003e \"\u003ctask\u003e\" [--trace-out \u003ctrace.json\u003e]\ncallsieve begin \u003cpath\u003e \"\u003ctask\u003e\" --client \u003ccodex|claude|copilot|opencode|antigravity|cursor|vscode|windsurf|continue|zed|junie|jetbrains|amp|goose|warp|cline|zoo|roo|generic\u003e [--trace-out \u003ctrace.json\u003e] [--proof-trace]\ncallsieve codex-session \u003cpath\u003e \"\u003ctask\u003e\" --trace-out \u003ctrace.json\u003e [--model \u003cname\u003e] [--expected-file \u003cpath\u003e]\ncallsieve enforce \u003cpath\u003e --client \u003ccodex|claude|copilot|opencode|antigravity|cursor|vscode|windsurf|continue|zed|junie|jetbrains|amp|goose|warp|cline|zoo|roo|generic\u003e [--trace \u003ctrace.json\u003e] [--strict] [--require-shim]\ncallsieve shim install \u003cpath\u003e [--force] [--strict]\ncallsieve shim doctor \u003cpath\u003e\ncallsieve shim uninstall \u003cpath\u003e\ncallsieve grep \u003cpath\u003e \"\u003cquery\u003e\" [--run-rg]\ncallsieve stats \u003cpath\u003e\n```\n\nExample:\n\n```bash\ncargo run -- index .\ncargo run -- index . --lsp\ncargo run -- demo . --task \"change login token expiry behavior\"\ncargo run -- query . \"where is auth handled?\"\ncargo run -- context . \"change login token expiry behavior\"\ncargo run -- agent-context . \"change login token expiry behavior\"\ncargo run -- agent-context . \"change login token expiry behavior\" --format markdown\ncargo run -- memory-clear .\ncargo run -- benchmark . \"change login token expiry behavior\"\ncargo run -- benchmark-suite . benchmarks/tasks.json\ncargo run -- benchmark-suite . benchmarks/callsieve-real-repo.json\ncargo run -- eval-retrieval benchmarks/retrieval-fixtures.json\ncargo run -- perf-report . --iterations 5\ncargo run -- proof-rehearsal --fix --resume\ncargo run -- trace-summary benchmarks/session-trace.example.json\ncargo run -- session-start . \"change login token expiry behavior\" --client codex --model gpt-5-codex --trace .callsieve/observed-session.json\ncargo run -- session-event .callsieve/observed-session.json --command \"callsieve agent-context . \\\"change login token expiry behavior\\\"\" --context-selected-file src/auth/session.ts --tokens 3000 --phase callsieve\ncargo run -- session-finish .callsieve/observed-session.json --out .callsieve/observed-summary.json\ncargo run -- trace-replay . benchmarks/callsieve-real-repo.json benchmarks/session-trace.local.json --limit 20\ncargo run -- trace-check benchmarks/session-trace.example.json --strict\ncargo run -- benchmark-report benchmarks/report-manifest.example.json\ncargo run -- benchmark-doctor benchmarks/report-manifest.example.json\ncargo run -- pilot-init benchmarks/evidence/pilot.local.json --sessions 1\ncargo run -- pilot-task add benchmarks/evidence/pilot.local.json . \"change login token expiry behavior\" --id auth-expiry --expected-file src/auth/session.ts --critical-file src/auth/session.ts\ncargo run -- pilot-run benchmarks/evidence/pilot.local.json --task-id auth-expiry --mode baseline --command \"rg login token expiry\" --files-read src/auth/session.ts --tokens 12000\ncargo run -- pilot-run benchmarks/evidence/pilot.local.json --task-id auth-expiry --mode callsieve --command \"callsieve agent-context . \\\"change login token expiry behavior\\\"\" --files-read src/auth/session.ts --tokens 3000\ncargo run -- record-codex-observed-session --manifest benchmarks/evidence/pilot.local.json --task-id auth-expiry --mode callsieve --command \"callsieve agent-context . \\\"change login token expiry behavior\\\"\" --tokens 3000 --files-read src/auth/session.ts\ncargo run -- record-observed-session --manifest benchmarks/evidence/pilot.local.json --client claude --model claude-opus-4-8 --task-id auth-expiry --mode callsieve --command \"claude -p \\\"change login token expiry behavior\\\" --output-format json\" --usage-json .callsieve/observed/auth-expiry-callsieve.json --files-read src/auth/session.ts\ncargo run -- collect-claude-observed-session --manifest benchmarks/evidence/observed-claude-oss-50.local.json --task-id ripgrep-ignore-walk-claude-r01 --mode callsieve --context-limit 4 --snippets-per-file 0 --max-budget-usd 0.50\ncargo run -- pilot-collect-ollama benchmarks/evidence/observed-generic-ollama-100.local.json --model qwen2.5-coder:7b --limit 10 --context-limit 24\ncargo run -- pilot-collect-lm-studio benchmarks/evidence/observed-generic-ollama-100.local.json --model qwen3-coder-next --base-url http://127.0.0.1:1234/v1 --limit 10 --context-limit 24\ncargo run -- pilot-qa benchmarks/evidence/pilot.local.json\ncargo run -- pilot-finalize benchmarks/evidence/pilot.local.json --out benchmarks/evidence/proof.local.json\ncargo run -- pilot-report benchmarks/pilot-manifest.example.json\ncargo run -- proof-report benchmarks/pilot-manifest.example.json\ncargo run -- enterprise-proof-report benchmarks/evidence/enterprise-proof-manifest.example.json\ncargo run -- pilot-doctor benchmarks/pilot-manifest.example.json\ncargo run -- evidence-pack benchmarks/pilot-manifest.example.json --anonymize\ncargo run -- policy-check benchmarks/session-trace.example.json --strict\ncargo run -- mcp\ncargo run -- mcp-config . --format json\ncargo run -- mcp-registry-manifest --out server.json\ncargo run -- status .\ncargo run -- daemon . --once\ncargo run -- daemon-status .\ncargo run -- watch .\ncargo run -- watch . --lsp\ncargo run -- agent-setup . --client codex\ncargo run -- bootstrap . --client generic --strict --force\ncargo run -- doctor . --client generic --strict\ncargo run -- doctor . --client generic --fix --strict\ncargo run -- codex-bootstrap . --model gpt-5-codex --force\ncargo run -- codex-hooks install . --strict --force\ncargo run -- codex-hooks doctor . --strict --smoke\ncargo run -- codex-hooks trust-ack .\ncargo run -- hook install . --client claude --strict --force --lsp\ncargo run -- claude-hooks doctor . --strict\ncargo run -- editor-hook . --editor cursor --force\ncargo run -- hook install . --client generic --strict --force --lsp\ncargo run -- hook doctor .\ncargo run -- hook uninstall .\ncargo run -- guard . \"change login token expiry behavior\" --trace-out .callsieve/session-trace.json\ncargo run -- begin . \"change login token expiry behavior\" --client generic --trace-out .callsieve/session-trace.json --proof-trace\ncargo run -- codex-session . \"change login token expiry behavior\" --trace-out .callsieve/codex-session.json --model gpt-5-codex\ncargo run -- enforce . --client codex --trace .callsieve/session-trace.json --strict\ncargo run -- shim install . --force --strict\ncargo run -- shim doctor .\ncargo run -- grep . \"change login token expiry behavior\"\n```\n\nReject invalid observed runs without deleting their audit trail:\n\n```bash\ncargo run -- pilot-task reject benchmarks/evidence/pilot.local.json --task-id auth-expiry --reason \"operator learned answer during paired run\"\n```\n\nFor the current 50-session observed Codex milestone, preregister the six-repo OSS task matrix with:\n\n```bash\ncargo run -- setup-observed-codex-oss-50\ncargo run -- setup-observed-claude-oss-50 --model claude-opus-4-8\n```\n\nRun the deterministic rehearsal separately:\n\n```bash\ncargo run -- proof-rehearsal --preflight\ncargo run -- proof-rehearsal --fix --resume\n```\n\nThe Rust rehearsal command is self-healing for local-safe issues. `--preflight` validates prerequisites, `--fix` rebuilds local indexes, creates ignored evidence directories, and regenerates missing controlled traces, `--resume` skips already-passed matching steps from `benchmarks/evidence/rehearsal-run.local.json`, and `--retry-count` retries transient failures. Output is JSON by default. It never clones repos, installs tools, deletes evidence, records observed sessions, or runs `proof-report`.\n\n`pilot-init` defaults to the strict 100-session claim protocol. Use `--sessions 1` only for local workflow shakedowns.\n\n## Current Capabilities\n\n- walks a repository while respecting common ignore rules\n- detects TypeScript, JavaScript, Python, Rust, PHP, Go, Java, C#, C, C++, Ruby, Kotlin, Swift, Scala, Dart, Lua, and shell source files plus agent-relevant docs and config files\n- extracts practical symbols with tree-sitter-backed parsing and deterministic fallbacks\n- extracts imports, references, and calls\n- can enrich references with local Language Server Protocol servers when `--lsp` is enabled\n- can build an optional local embeddings cache with `--embeddings` for opt-in hybrid retrieval\n- indexes CODEOWNERS ownership and recent git activity for local ranking and context signals\n- can parse stack traces through `agent-context --error` to promote crash-related files\n- indexes bounded content terms for Markdown, JSON, TOML, YAML, and text without returning full files\n- stores a local JSON index at `.callsieve/index.json`\n- returns compact JSON for agent consumption, with Markdown output available for direct reading\n- ranks matches with deterministic, explainable scoring\n- builds compact read-first context packets for coding tasks\n- boosts package manifests for dependency and setup tasks\n- boosts context with import, caller, and callee proximity\n- provides an `agent-context` wrapper agents can call before grep\n- keeps a small local task-memory hint cache for repeated task families\n- clears local task memory with `memory-clear` for cold-run testing\n- runs a `demo` command that indexes, returns read-first files, and reports context payload reduction\n- installs lifecycle hooks or plugins for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity CLI, and Cline\n- exposes a minimal MCP stdio server so agents can call CallSieve before grep\n- prints portable JSON/TOML MCP configs for generic AI CLIs with `mcp-config` and a local-first MCP Registry `server.json` descriptor with `mcp-registry-manifest`\n- reports platform-neutral `context_payload_reduction` versus a naive grep/read loop\n- evaluates retrieval recall against expected and critical file fixtures with `eval-retrieval`\n- reports local p50/p95 context latency with `perf-report`\n- records real observed agent session events and summarizes baseline versus CallSieve-assisted phases\n- keeps controlled replay evidence separate from observed-session evidence\n- aggregates benchmark evidence across multiple local repositories\n- produces pilot and top-level proof reports that combine benchmark, observed trace, controlled replay, policy, freshness, bootstrap, daemon, and LSP evidence\n- produces an opt-in enterprise proof report that gates broad claims on 1,000 observed sessions, multi-client coverage, scale proxies, strict trace policy, and PMF evidence\n- produces anonymized evidence packs for external pilot aggregation\n- provides CI-friendly strict policy checks for context-first sessions\n- validates evidence manifests before reports\n- reports index freshness and keeps indexes fresh with a local watcher or daemon state loop\n- generates client-specific agent rules that require CallSieve before broad grep\n- writes an explicit first command into agent setup: `callsieve agent-context \u003crepo\u003e \"\u003ctask\u003e\"`\n- bootstraps the local adoption stack with `bootstrap`: index, agent config, daemon state, and optional strict shims\n- audits and repairs local adoption setup with `doctor --fix`\n- starts lightweight task sessions with `begin`, returning context and optionally writing a trace stub for strict audits\n- guards context-first sessions and can write trace stubs for policy audits\n- starts controlled Codex/ChatGPT context-first replay traces with model tags\n- bootstraps project-local hooks, resolved MCP config, rules, and grep shims without global PATH/profile mutation\n- generates project-local MCP configs, rules, and editor hook templates for supported agents without mutating global user config\n- installs repo-local agent launchers with `hook install` so shims and daemon startup stay process-local\n- audits agent setup, traces, index freshness, and optional shim state with `enforce`\n- installs an opt-in local `callsieve` launcher plus `rg`/`grep` shims for PATH-level interception\n- wraps grep workflows so CallSieve context is returned before the original `rg` or `grep` command is replayed\n- runs a resumable public 50-issue lexical-vs-hybrid A/B benchmark with `bench-run --compare --resume`\n\n## Example Query Output\n\n```json\n{\n  \"query\": \"where is auth handled?\",\n  \"root\": \".\",\n  \"matches\": [\n    {\n      \"rank\": 1,\n      \"score\": 90,\n      \"file\": \"src/auth/session.ts\",\n      \"language\": \"typescript\",\n      \"symbol\": {\n        \"name\": \"createSession\",\n        \"kind\": \"function\",\n        \"lines\": [12, 48],\n        \"visibility\": \"exported\",\n        \"signature\": \"export function createSession(...)\"\n      },\n      \"why\": [\"keyword overlap: auth, session\"]\n    }\n  ],\n  \"stats\": {\n    \"searched_files\": 182,\n    \"matched_files\": 7,\n    \"matched_symbols\": 12\n  }\n}\n```\n\n## Example Context Output\n\n```json\n{\n  \"task\": \"change login token expiry behavior\",\n  \"root\": \".\",\n  \"read_first\": [\n    {\n      \"rank\": 1,\n      \"score\": 140,\n      \"file\": \"src/auth/session.ts\",\n      \"language\": \"typescript\",\n      \"symbols\": [\n        {\n          \"name\": \"createSession\",\n          \"kind\": \"function\",\n          \"lines\": [12, 48],\n          \"visibility\": \"exported\",\n          \"signature\": \"export function createSession(...)\"\n        }\n      ],\n      \"snippets\": [\n        {\n          \"lines\": [12, 30],\n          \"text\": \"export function createSession(...) { ... }\"\n        }\n      ],\n      \"imports\": [\"src/auth/token.ts\"],\n      \"referenced_by\": [\"src/auth/session.test.ts\"],\n      \"blast_radius\": {\n        \"imports\": [\"src/auth/token.ts\"],\n        \"referenced_by\": [\"src/auth/session.test.ts\"],\n        \"tests\": [\"src/auth/session.test.ts\"],\n        \"calls\": [\"src/auth/token.ts\"],\n        \"risk\": \"medium\"\n      },\n      \"calls\": [\n        {\n          \"file\": \"src/auth/session.ts\",\n          \"symbol\": \"createSession\",\n          \"target\": \"tokenFor\",\n          \"target_file\": \"src/auth/token.ts\",\n          \"kind\": \"call\",\n          \"line\": 13\n        }\n      ],\n      \"related_tests\": [\n        {\n          \"file\": \"src/auth/session.test.ts\",\n          \"symbols\": [\"createSession returns token-backed session\"]\n        }\n      ],\n      \"why\": [\n        \"exact symbol match: createSession\",\n        \"keyword overlap: auth, session\",\n        \"references matched file: src/auth/token.ts\"\n      ]\n    }\n  ],\n  \"stats\": {\n    \"candidate_matches\": 30,\n    \"selected_files\": 5,\n    \"selected_symbols\": 8,\n    \"related_tests\": 2\n  }\n}\n```\n\n## Example Benchmark Output\n\n```json\n{\n  \"task\": \"change login token expiry behavior\",\n  \"estimator\": \"local deterministic token estimate\",\n  \"baseline\": {\n    \"strategy\": \"naive grep term scan plus full matched-file reads\",\n    \"grep_terms\": [\"login\", \"token\", \"expiry\"],\n    \"grep_commands\": 3,\n    \"matched_files\": 18,\n    \"estimated_total_tokens\": 24000\n  },\n  \"callsieve\": {\n    \"strategy\": \"callsieve context packet\",\n    \"selected_files\": 6,\n    \"estimated_packet_tokens\": 4200\n  },\n  \"savings\": {\n    \"avoided_grep_commands\": 2,\n    \"avoided_file_reads\": 12,\n    \"estimated_token_savings\": 19800,\n    \"estimated_token_reduction_percent\": 82.5\n  }\n}\n```\n\n## Example Benchmark Suite\n\n```json\n{\n  \"tasks\": [\n    {\n      \"id\": \"auth-token-expiry\",\n      \"task\": \"change login token expiry behavior\",\n      \"expected_files\": [\"src/auth/session.ts\", \"src/auth/token.ts\"],\n      \"observed\": {\n        \"baseline\": { \"grep_commands\": 12, \"file_reads\": 18, \"tokens\": 42000 },\n        \"callsieve\": { \"grep_commands\": 1, \"file_reads\": 6, \"tokens\": 9000 }\n      }\n    }\n  ]\n}\n```\n\n`benchmark-suite` reports expected-file recall, aggregate `context_payload_reduction`, legacy estimated token-savings fields, and optional observed session savings when real agent trace numbers are supplied. `context_payload_reduction` is the platform-neutral proxy for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity CLI, Cursor, VS Code, Windsurf, Continue, Zed, Junie, JetBrains AI Assistant, Amp, Goose, Warp, Cline, Zoo Code, the deprecated Roo alias, generic stdio MCP tools, and local agents. It estimates only the prompt context payload CallSieve controls, not whole-session transcript tokens.\n\n`eval-retrieval` runs the same task fixture shape against the actual `agent-context` selection path and reports recall@k, critical recall, selected tokens, and failure reasons. It exits nonzero when a critical file is missed. `perf-report` runs fixed local tasks and reports p50/p95 latency for index load plus context generation.\n\n`trace-replay` generates deterministic baseline versus CallSieve trace JSON from a suite. It is tagged with `metadata.collection = \"controlled_replay\"` and is useful before real observed session evidence exists.\n\nUse `session-start`, `session-event`, and `session-finish` for real observed agent sessions across hook-capable and MCP-capable clients, including Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity CLI, Cursor, VS Code, Windsurf, Continue, Zed, Junie, JetBrains AI Assistant, Amp, Goose, Warp, Cline, Zoo Code, and local agents. These traces are tagged with `metadata.collection = \"observed_session\"` and keep ordered events with command classification, actual files read, CallSieve-selected context files, optional token counts, and phase (`baseline` or `callsieve`).\n\n`files_read` means actual file-read tool or command paths. Use `context_selected_files` or `--context-selected-file` for files selected into a CallSieve read-first packet when no whole-file read happened. Only `metadata.collection = \"observed_session\"` is counted as observed proof. Lifecycle collections such as `codex_hook_trace`, `claude_hook_trace`, and `\u003cclient\u003e_hook_trace` are guardrail telemetry and are excluded from observed proof gates.\n\nSee [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for the real-repo benchmark pack, session trace format, replay traces, and miss analysis fields.\n\n## Example Trace Summary\n\n```json\n{\n  \"sessions\": 3,\n  \"baseline_tokens\": 84000,\n  \"callsieve_tokens\": 27000,\n  \"token_savings\": 57000,\n  \"token_reduction_percent\": 67.85714285714286,\n  \"avoided_grep_commands\": 18,\n  \"avoided_file_reads\": 31,\n  \"files_still_missed\": 1\n}\n```\n\n## Example Benchmark Report Manifest\n\n```json\n{\n  \"repos\": [\n    {\n      \"label\": \"callsieve\",\n      \"path\": \".\",\n      \"suite_path\": \"benchmarks/callsieve-real-repo.json\",\n      \"trace_path\": \"benchmarks/session-trace.example.json\"\n    }\n  ]\n}\n```\n\n`benchmark-report` does not clone repositories or use the network. Every repo path, suite path, and trace path must already exist locally.\n\nUse `benchmark-doctor` before a report to catch missing repos, missing indexes, bad suite JSON, and bad trace JSON.\n\n## Example Pilot Report Manifest\n\n```json\n{\n  \"thresholds\": {\n    \"minimum_recall\": 1.0,\n    \"minimum_token_reduction_percent\": 50.0,\n    \"minimum_observed_sessions\": 1,\n    \"minimum_observed_token_reduction_percent\": 50.0,\n    \"minimum_external_repos\": 0,\n    \"minimum_planned_tasks\": 1,\n    \"maximum_controlled_replay_ratio\": 0.25,\n    \"maximum_trace_violations\": 0,\n    \"maximum_critical_misses\": 0,\n    \"require_fresh_index\": true,\n    \"require_lsp_where_available\": false,\n    \"require_codex_bootstrap\": false,\n    \"require_transcript_token_accounting\": false\n  },\n  \"audit\": {\n    \"planned_tasks\": 1,\n    \"rejected_sessions\": 0,\n    \"token_accounting_sources\": [\"transcript_context_tokens\"]\n  },\n  \"repos\": [\n    {\n      \"label\": \"callsieve\",\n      \"path\": \".\",\n      \"languages\": [\"typescript\", \"javascript\", \"python\", \"rust\"],\n      \"suite_paths\": [\"benchmarks/callsieve-real-repo.json\"],\n      \"trace_paths\": [\"benchmarks/session-trace.example.json\"],\n      \"policy_trace_paths\": [\"benchmarks/session-trace.example.json\"]\n    }\n  ]\n}\n```\n\n`pilot-report` is the pilot-proof artifact: it combines multi-repo benchmark recall, estimated token savings, observed trace savings, controlled replay counts, strict before-grep policy checks, index freshness, daemon state, Codex bootstrap coverage, and LSP coverage.\n\n`proof-report` is the top-level claim artifact. It exposes planned tasks, rejected-session audit count, observed sessions, transcript-token provenance, controlled replay sessions, external repo coverage, observed token reduction, controlled replay ratio, freshness, daemon, bootstrap, and LSP status in one JSON object. Controlled replay is never counted as observed evidence.\n\n`enterprise-proof-report` is the broad-claim artifact. It is opt-in and fails unless the manifest meets the enterprise gates: 1,000 paired observed sessions, 50 repos, 10 Microsoft-scale OSS proxies, manifest-configured client coverage, 5 languages, 10 task categories, 90% positive per-session savings, 75% of sessions above 30% savings, zero critical misses, zero strict trace violations, zero controlled replay, full transcript token accounting, and paid-pilot PMF evidence. See [docs/ENTERPRISE_PROOF.md](docs/ENTERPRISE_PROOF.md) and [benchmarks/evidence/enterprise-proof-manifest.example.json](benchmarks/evidence/enterprise-proof-manifest.example.json).\n\nEvidence is separated into three tiers:\n\n- Rehearsal: deterministic retrieval fixtures, benchmark reports, perf reports, platform-neutral `context_payload_reduction`, and controlled replay traces.\n- Supplemental: Ollama or local-model collection, useful for rehearsal but not Codex claim proof.\n- Claim-counted: real paired Codex sessions with transcript token accounting, transcript-backed files read, strict policy checks, and `pilot-qa` passing before `proof-report`.\n\nUse `context_payload_reduction` when comparing CallSieve across agent platforms. Use observed token reduction only when a real paired transcript provides audited token counts.\n\n`proof-report` should only be used as claim proof after `pilot-qa` passes for the claim-counted manifest.\n\nFor the strict observed-session collection protocol, see [docs/OBSERVED_SESSIONS.md](docs/OBSERVED_SESSIONS.md). The 50-session milestone is the first credible public proof target; the enterprise proof target remains gated at 1,000 paired observed sessions.\n\nUse `evidence-pack` when you need a shareable aggregate for external pilots:\n\n```bash\ncargo run -- evidence-pack benchmarks/pilot-manifest.example.json --anonymize\n```\n\nWith `--anonymize`, repo paths, labels, suite paths, and trace paths are redacted while aggregate metrics remain intact.\n\n## Agent Enforcement\n\nUse `bootstrap` when you want the whole local adoption stack in one command: rebuild the index, write client-specific MCP config and policy files, start the daemon state path, and optionally install strict local shims. It does not mutate global shell profiles, global user PATH, or cloud configuration.\n\n```bash\ncargo run -- bootstrap . --client generic --strict --force --lsp\ncargo run -- doctor . --client generic --strict\ncargo run -- doctor . --client generic --fix --strict\n```\n\n`doctor` reports local adoption checks: fresh index, generated agent files, optional Codex bootstrap files, strict shim files, and whether the shim directory is currently on the agent shell PATH. With `--fix`, it repairs missing or stale local pieces it can safely write under the repo. PATH changes remain an explicit shell choice for the launched agent process.\n\nUse `begin` as the lightweight entrypoint for a task session. It returns the normal read-first context packet and, with `--trace-out`, writes the first context event so `trace-check --strict` can audit later grep or file reads:\n\n```bash\ncargo run -- begin . \"change login token expiry behavior\" --client generic --trace-out .callsieve/session-trace.json --proof-trace\ncargo run -- trace-check .callsieve/session-trace.json --strict\n```\n\nAdd `--proof-trace` when the trace is used as claim evidence. It labels the trace as explicit session events and does not depend on Codex `PostToolUse`. After a proof trace starts, every added `session-event` must include `--tokens` and explicit `--phase baseline|callsieve`.\n\nUse `agent-setup` when you only need local MCP config plus a short CallSieve-first policy file for Codex, Claude, Copilot, OpenCode, Antigravity, Cursor, VS Code, Windsurf, Continue, Zed, Junie, JetBrains AI Assistant, Amp, Goose, Warp, Cline, Zoo, Roo alias, or generic MCP clients:\n\n```bash\ncargo run -- agent-setup . --client codex --force\n```\n\nFor coding tasks, the policy is: call `callsieve_context` before broad grep, `rg`, repository-wide search, or repeated file reads. Read `read_first` files first; grep only if the context packet is insufficient.\n\nUse `hook install` when you want the easiest repo-local agent entrypoint. It builds the index, writes client setup, installs strict shims, and creates `.callsieve/agent-launch.ps1` plus `.callsieve/agent-launch.sh`. For hook-capable clients, it also writes local project hooks or plugins. Cursor, VS Code, Windsurf, Continue, Zed, Junie, JetBrains AI Assistant, Amp, Goose, Warp, and Zoo use MCP/rules/templates plus shims only.\n\n```bash\ncargo run -- hook install . --client generic --strict --force --lsp\ncargo run -- hook doctor .\n```\n\nHook setup does not mutate global shell profiles or user PATH. Remove the repo-local launchers and shims with:\n\n```bash\ncargo run -- hook uninstall .\n```\n\nFor Codex, lifecycle hooks are the primary enforcement path:\n\n```bash\ncargo run -- codex-hooks install . --strict --force\ncargo run -- codex-hooks doctor . --strict --smoke\ncargo run -- codex-hooks trust-ack .\n```\n\nCodex hooks use the `slim` profile. The generated `.codex/hooks.json` runs local `callsieve codex-hook ...` handlers. `UserPromptSubmit` injects compact CallSieve context, `PreToolUse` blocks broad search before context, and `PermissionRequest` denies escalated pre-context search. Codex `PostToolUse` and `Stop` are intentionally not installed because pre-tool hooks enforce the policy and post-tool or stop-time prompts are optional. Run `codex-hooks doctor --strict --smoke` for local handler smoke tests, and add `--fix` to archive stale hook state or trace files under `.callsieve/codex-hooks/archive/`. Review and trust project hooks in Codex with `/hooks`, then run `codex-hooks trust-ack .` to record a local marker tied to the current hook file hash.\n\nFor Claude Code, `hook install --client claude` gives all three local layers: hooks, shims, and MCP:\n\n```bash\ncargo run -- hook install . --client claude --strict --force --lsp\ncargo run -- claude-hooks doctor . --strict\ncargo run -- enforce . --client claude --strict\n```\n\nThis writes `.mcp.json`, `CLAUDE.md`, `.claude/settings.local.json`, `.callsieve/agent-launch.ps1`, `.callsieve/agent-launch.sh`, and `.callsieve/bin/*`. The Claude Code hooks run local `callsieve claude-hook ...` handlers, inject context at `UserPromptSubmit`, block `Bash`, `Read`, `Grep`, and `Glob` before context in strict mode, and record `.callsieve/claude-hooks/*.trace.json`. Review and trust project hooks in Claude Code with `/hooks`.\n\nFor GitHub Copilot, OpenCode, Antigravity CLI, and Cline, use the same lifecycle pattern:\n\n```bash\ncargo run -- hook install . --client copilot --strict --force --lsp\ncargo run -- copilot-hooks doctor . --strict\ncargo run -- hook install . --client opencode --strict --force --lsp\ncargo run -- hook install . --client antigravity --strict --force --lsp\ncargo run -- hook install . --client cline --strict --force --lsp\n```\n\nCopilot writes `.github/copilot-instructions.md`, `.github/agents/callsieve-context.agent.md`, `.github/copilot-mcp.json`, and `.github/hooks/callsieve.json`. OpenCode writes `opencode.json`, `.opencode/CALLSIEVE.md`, and `.opencode/plugins/callsieve.js`. Antigravity writes `.agents/mcp_config.json`, `.agents/hooks.json`, `.agents/skills/callsieve-context.md`, and `.agents/rules/callsieve.md`. Cline writes `.cline/mcp.json`, `.cline/rules/callsieve.md`, `.clinerules/callsieve.md`, and `.cline/hooks/*`. Copilot cloud agents are template-only unless the local `callsieve` binary is installed inside the sandbox.\n\nFor VS Code, Windsurf, Continue, Zed, Junie, JetBrains AI Assistant, Amp, Goose, and Warp, CallSieve writes MCP/rule/skill/setup templates only. Strict mode requires those generated files, a fresh index, daemon state, and local shims, but it does not require lifecycle hooks. Global or user config files are not mutated automatically. Warp cloud-agent templates work only when the Warp/Oz runtime can execute the local `callsieve` binary.\n\nUse `guard` to start a context-first task and write a trace stub, then use strict `trace-check` to audit actual sessions:\n\n```bash\ncargo run -- guard . \"change login token expiry behavior\" --trace-out .callsieve/session-trace.json\ncargo run -- trace-check .callsieve/session-trace.json --strict\ncargo run -- policy-check .callsieve/session-trace.json --strict\ncargo run -- enforce . --client codex --trace .callsieve/session-trace.json --strict\n```\n\n`policy-check` exits nonzero when a trace violates the context-first rule, so it can be used in CI. `enforce` checks generated agent files, index freshness, optional trace policy, hook surfaces where supported, and shim state. In strict mode, first-class named clients require local shim files; generic clients can still opt into failing on missing shims with `--require-shim`.\n\nFor Codex/ChatGPT controlled replay, use `codex-session` instead of a generic guard. It writes a trace with `client: codex-chatgpt`, a model label, a deterministic grep/read baseline, and a CallSieve-first assisted side:\n\n```bash\ncargo run -- codex-session . \"change login token expiry behavior\" --trace-out .callsieve/codex-session.json --model gpt-5-codex\ncargo run -- trace-summary .callsieve/codex-session.json\ncargo run -- enforce . --client codex --trace .callsieve/codex-session.json --strict\n```\n\nRun the same task with different `--model` labels when comparing available Codex/ChatGPT models. CallSieve records and audits the sessions you run; it does not invoke hidden ChatGPT models itself.\n\n`codex-session` is controlled replay evidence. For real observed sessions, use:\n\n```bash\ncargo run -- session-start . \"change login token expiry behavior\" --client codex --model gpt-5-codex --trace .callsieve/observed-session.json\ncargo run -- session-event .callsieve/observed-session.json --command \"callsieve agent-context . \\\"change login token expiry behavior\\\"\" --context-selected-file src/auth/session.ts --tokens 3000 --phase callsieve\ncargo run -- session-finish .callsieve/observed-session.json --out .callsieve/observed-summary.json\n```\n\nUse `codex-bootstrap` for Codex-first project setup without mutating global shell profiles or user PATH:\n\n```bash\ncargo run -- codex-bootstrap . --model gpt-5-codex --force\n```\n\nIt writes `.codex/config.toml`, `.codex/CALLSIEVE.md`, `.codex/hooks.json`, `.callsieve/bin` launchers/shims, and `.callsieve/codex-launch.ps1` / `.callsieve/codex-launch.sh`. The MCP config points at the resolved CallSieve executable instead of relying on a global PATH entry. The lifecycle hooks inject context and block broad search before context. The launchers start `callsieve daemon --background --lsp`, prepend `.callsieve/bin` only for that launched process, and print the first required `callsieve agent-context` command.\n\nThis repo includes `benchmarks/codex-chatgpt-manifest.example.json` as the Codex pilot manifest fixture. Copy it to an ignored `.local.json` path before recording local runs.\n\nFor hard opt-in grep interception, install local wrappers and prepend `.callsieve/bin` to the agent shell PATH:\n\n```bash\ncargo run -- shim install . --force --strict\ncargo run -- shim doctor .\n```\n\nThe install writes a project-local `callsieve` launcher plus wrappers that call the hidden `callsieve shim-run` helper before passing through to the real `rg` or `grep` command captured at install time. `shim-run` parses common search arguments, returns CallSieve context first, then replays the original command arguments against the real search binary. With `--strict`, shim-mediated grep writes `.callsieve/shim-trace.json` events that strict trace checks can flag when grep happens before CallSieve context. The wrappers are inert until `.callsieve/bin` is prepended to the agent shell PATH for that process.\n\n## Fresh Indexes\n\n`status` reports index freshness, schema version, watch status, watcher mode, index age, stale/changed/removed files, LSP server availability, and whether the saved index was actually LSP-enriched. `watch` refreshes the index once by default, or continuously when run with `--foreground`:\n\n```bash\ncargo run -- status .\ncargo run -- watch .\ncargo run -- watch . --lsp\ncargo run -- watch . --foreground\n```\n\nThe V1 watcher is a portable polling refresh path with no extra daemon dependency. It keeps the on-disk JSON index current while preserving the local-first model.\n\nUse `daemon` for a stateful local refresh loop:\n\n```bash\ncargo run -- daemon . --once\ncargo run -- daemon . --background --lsp\ncargo run -- daemon . --foreground --lsp\ncargo run -- daemon-status .\ncargo run -- daemon-stop .\n```\n\nThe daemon writes `.callsieve/daemon.json` with PID, `started_at`, `last_indexed_at`, `last_error`, and `index_generation`. `status` includes the saved daemon state. Background start is available through `callsieve daemon \u003cpath\u003e --background`; foreground or `--once` is easier to inspect during pilots.\n\n## LSP Enrichment\n\nThe default index is fast and deterministic. Add `--lsp` when you want CallSieve to ask installed local language servers for higher-confidence reference edges:\n\n```bash\ncargo run -- index . --lsp\n```\n\nCallSieve does not install servers, clone repositories, or use the network. It detects these local commands when the matching language is indexed:\n\n- TypeScript/JavaScript: `typescript-language-server --stdio`\n- Python: `pyright-langserver --stdio`\n- Rust: `rust-analyzer`\n- PHP: `intelephense --stdio`\n- Go: `gopls`\n- C/C++: `clangd`\n- Ruby: `ruby-lsp`\n- Lua: `lua-language-server`\n- C#: `csharp-ls`\n- Java: `jdtls`\n- Kotlin: `kotlin-language-server`\n- Swift: `sourcekit-lsp`\n- Scala: `metals`\n- Dart: `dart language-server --protocol=lsp`\n\nIf a server is missing or fails, CallSieve keeps the tree-sitter and heuristic graph and reports per-language availability plus failure reasons in `status`. LSP-derived edges use sources such as `\"lsp_reference\"`, `\"lsp_definition\"`, `\"lsp_implementation\"`, and `\"lsp_type_definition\"` with `\"confidence\": 1.0`; tree-sitter edges use `0.8`, and heuristic edges use `0.5`.\n\n## MCP Integration\n\n`callsieve mcp` runs a stdio JSON-RPC server with these tools:\n\n- `callsieve_context`: zero-AI-model-token local retrieval; build the compact read-first packet for a coding task before grep\n- `callsieve_symbol`: find indexed symbols with import and reference hints\n- `callsieve_focus`: reveal targeted symbols and snippets for one selected file\n- `callsieve_related`: reveal imports, callers, callees, and blast-radius hints for one selected file\n- `callsieve_tests`: reveal tests likely related to one selected file\n- `callsieve_stats`: inspect index coverage\n- `callsieve_status`: inspect freshness, watch, schema, and LSP enrichment state\n- `callsieve_trace_check`: audit whether a session grepped before CallSieve\n- `callsieve_benchmark`: estimate platform-neutral context payload reduction against a grep/read loop\n\n`callsieve_context` self-heals a missing or stale `.callsieve/index.json` by rebuilding the local index before returning context. MCP responses include freshness and timing metadata. The MCP server does not install shims, mutate client config, start the daemon, or send code to a remote service.\n\nUse `callsieve mcp-config \u003crepo\u003e --format json` or `--format toml` for any AI CLI that supports stdio MCP but does not have a dedicated CallSieve setup command. Use `callsieve mcp-registry-manifest --out server.json` to generate a local-first MCP Registry descriptor for `callsieve mcp`; it never contacts the network or publishes automatically.\n\nSee [docs/INSTALL.md](docs/INSTALL.md) for human install and client setup, [docs/AGENT_CLI.md](docs/AGENT_CLI.md) for AI CLI behavior, and [docs/MCP.md](docs/MCP.md) for MCP examples across supported clients.\n\n## Feedback FAQ\n\n**Does it need to be MCP?** No. MCP is one integration path. The same retrieval path is available through `callsieve agent-context`, JSON output, Markdown output, lifecycle hooks or plugins where clients support them, and repo-local shims.\n\n**Why not just Markdown or CSV?** Markdown is now available for direct reading, and JSON remains the default because agents and tooling need nested fields for files, symbols, snippets, tests, scores, and trace policy. CSV loses too much structure for this workflow.\n\n**Is this already solved by IDE indexes?** IDE indexes are useful, but they are usually tied to one editor and optimized for interactive humans. CallSieve is agent-facing, cross-tool, local-first, auditable, and tuned to produce a compact read-first packet before an agent spends tokens on broad search.\n\n**Does it work for PHP?** Yes. PHP files are indexed with lightweight detection for functions, classes, interfaces, traits, enums, imports, includes, references, and related snippets. If `intelephense` is installed, `--lsp` can report PHP language-server availability too.\n\n## Local-First Guarantees\n\n- no cloud services\n- no API keys\n- no proprietary code leaves the machine\n- no SaaS app, auth system, web dashboard, or vector DB in the current local-first product\n- MIT-licensed local core, with paid pilots and support kept separate from code access\n\n## License\n\nCallSieve is licensed under the [MIT License](LICENSE).\n\n## Retrieval Model\n\nCallSieve is sparse attention for the codebase before the prompt exists.\n\n```text\nUser question\n  -\u003e repo index\n  -\u003e top-k files, symbols, tests, and import neighbors\n  -\u003e compact snippets\n  -\u003e agent context\n```\n\nThe current retrieval model uses deterministic ranking first:\n\n- exact symbol match\n- exact path or filename match\n- exported symbol substring match\n- local symbol substring match\n- keyword overlap\n- likely related tests\n- direct import neighbors where available\n\nEmbeddings, Git history, editor-specific extensions, and durable cross-repo memory are later phases.\n\n## Development\n\n```bash\ncargo fmt --check\ncargo test\ncargo clippy --all-targets -- -D warnings\n```\n\nOn Windows, `cargo test` may fail with `Access is denied` when replacing `target\\debug\\callsieve.exe` if a previous CallSieve daemon, MCP server, or shim-launched process still holds the binary. Stop the repo daemon first:\n\n```bash\ncargo run -- daemon-stop .\n```\n\nIf the binary is still locked, terminate the stale process and rerun tests:\n\n```cmd\ntaskkill /IM callsieve.exe /F\ncargo test\n```\n\nFor verification while investigating a lock, use a separate target directory:\n\n```bash\ncargo test --target-dir \u003ctemp-dir\u003e\\callsieve-target-test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilipjohnbasile%2Fcallsieve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilipjohnbasile%2Fcallsieve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilipjohnbasile%2Fcallsieve/lists"}