Needle is a local-first task router and proof-gated semantic cache for coding agents. It moves bounded repository work away from an expensive frontier model, validates the resulting evidence, and reuses that evidence only while it remains fresh and sufficient.

Project status · Roadmap · Documentation · Contributing · Security policy · Benchmark evidence

Frontier coding models are capable, but repository discovery can consume a large portion of their context and cost. Needle treats that work as a bounded request that can be routed to a smaller supervised worker. When the same validated knowledge is useful again, a proof-gated cache can avoid the worker as well.

The product has two economic layers:

1. Routing: delegate suitable discovery to a lower-cost worker.
2. Reuse: avoid that worker when certified evidence already satisfies the request.

Needle is not a coding client, code graph, search engine, language server, or replacement for the main model. Those systems can provide discovery tools; Needle owns routing, validation, reuse, and bounded continuation.

flowchart LR
    U["User task"] --> M["Frontier model"]
    M --> N["Typed need"]
    N --> R{"Proof-gated resolver"}
    R -->|"Fresh sufficient proof"| F["Bounded FrontierView"]
    R -->|"Missing obligations"| W["Supervised worker"]
    W --> V["Trusted validation"]
    V --> C["Certified artifact cache"]
    C --> F
    F --> M
    M --> A["Final answer"]

The main model can declare a need through the development-only unversioned @@need lifecycle protocol or call the structured need_context MCP tool. Both transports compile to the same semantic domain model. Before returning cached context, Needle checks exact subject identity, semantic world, dependency freshness, contradictions, residual intent, and obligation coverage.

• Typed routes for implementation location, state-flow tracing, and focused tests.
• Validator-derived artifacts, dependency manifests, validation certificates, and replayable sufficiency proofs.
• Exact, coverage, composite, partial, and narrowly bounded claim-level reuse.
• A read-only evidence worker supervised through Codex App Server.
• Disposable source checkouts, trusted-test approval, bounded repair, cleanup, and process-tree cancellation.
• Sequential and steer-delivered multi-need coordination.
• A structured stdio MCP server with need_context, prepare_change, and verify_change.
• A resident runtime, SQLite persistence, IPC, and an embedded React control plane.
• Isolated change preparation, independent verification, one bounded repair, and explicit parent-owned apply.

• Claim authority is currently narrow and provider-backed claim reuse has not been validated.
• Verified changes have deterministic offline coverage but no provider-backed patcher or verifier observation.
• Windows has live calibration evidence; Linux and macOS currently have code and CI support only.
• The web control plane is an operational development interface, not a stable end-user product.

• Stable installation or configuration compatibility.
• A public beta or supported deployment.
• Cross-platform live validation.
• A powered multi-task benchmark and statistically supported savings claim.
• Automatic commits, pushes, merges, or releases.

See Project status for current maturity, evidence levels, capabilities, and milestones.

Needle publishes reproducible reports for the observations used to evaluate routing and reuse. Each report records the task, source snapshot, models, pricing basis, observed result, and limitations.

Earlier routing and cache observations remain useful as calibration of an earlier product boundary. They do not establish claims about the current proof kernel. See Benchmarking for the comparison contract and the evidence index for accepted reports.

• Evidence workers are read-only.
• Patch workers may write only inside a disposable checkout and only within paths declared by the parent.
• The active worktree is never a worker's writable root.
• Workers receive no network, credentials, project instructions, hooks, plugins, external MCP servers, or multi-agent capability.
• Test execution is optional, trusted-repository only, policy-bound, and confined to disposable locations.
• Unknown validity becomes BYPASS; stale or contradicted evidence is never served.
• Applying a verified patch is a separate, explicit, parent-owned operation.

Read Security and approvals before changing a worker, command, or apply boundary.

This is a source-development workflow, not an installation guide. A clean clone must build the frontend before compiling the Rust binary because the binary embeds crates/needle-app/web/dist.

Requirements:

• Rust 1.90.0 with rustfmt and clippy;
• Codex 0.144.0 for the currently validated adapter;
• Node.js 22.22.0 or newer and npm for building the embedded frontend assets (Node is not needed at runtime).

cd crates/needle-app/web
npm ci
npm run build
cd ../../..
cargo build --locked --workspace
cargo test --locked --workspace

The packages intentionally remain publish = false. Do not depend on the CLI, database schema, MCP schema, or configuration as a stable interface.

Continue with Developer setup for profile initialization and serving, and see Development and troubleshooting.

Needle is organized as a five-crate Rust workspace:

• Project status and milestones
• Product roadmap
• Documentation index
• Architecture
• Artifacts and cache
• MCP transport
• Verified changes
• Runtime and web control plane
• Benchmarking
• Security policy
• Contributing
• Code provenance

AI may assist analysis, code, tests, and documentation. A human contributor must read and understand the complete change, verify every claim, finalize the commit and pull-request text, and personally perform commit, push, and pull-request publication. See CONTRIBUTING.md for the complete policy.

Needle is available under the Apache License 2.0.