mirror of
https://github.com/usips/trufflepig.git
synced 2026-10-24 12:08:09 -04:00
Joshua MoonandCodex
1f7e4a2efc
Align the shared Codex, Claude, Grok, Kimi, and Muse skill with executable cursor follow-ups, quoted exclusions, precise path matching, incomplete coverage, and bounded worktree fallback. Keep repository contract links usable in copied skills and check unverified parent-byte reads before claiming current source. Refresh Claude startup and tool guidance. Skip unrelated shell programs before source searches and avoid treating filtered cat/sed pipelines as pure reads. Validated by all 75 harness tests including Bun execution, plus real CLI paging, filters, worktree publication, stale reads, and concurrent acceptance. Co-authored-by: Codex <[email protected]>
Trufflepig
Trufflepig is a local search engine for coding agents working in large
repositories. Instead of grep output that floods the context window, an agent
gets one ranked, token-budgeted page of hits with stable handles, then reads
exactly the source it needs, verified against the bytes on disk. Pre-alpha,
Linux only.
What an agent gets
- Bounded answers. Every response fits a token budget, 600
o200k_basetokens by default, ranked file-first with one representative hit per file. Truncation and partial coverage are reported, never silent. (CLI) - Handles instead of re-searching. Each hit carries an immutable handle.
showreturns its source with the revision and averified:footer;morepages;ctxandrefsfollow relationships;mapoutlines a module. Handles survive restarts and never drift to a newer query. (retrieval contract) - Structure, not just text. Symbols, definitions, references, and resolved-versus-candidate relationships for Rust, TypeScript/JavaScript, C#, PHP, Luau, and DreamMaker. Everything else stays text-searchable. (language contract)
- History without a checkout.
hist,since,diff, andblameover local Git objects with exact before/after reads. Needs Git 2.55 or newer. (history contract) - Multi-repo workspaces, opt-in semantic retrieval and reranking with a 500 ms deadline and lexical fallback, and a per-session audit of every call. (workspace, semantic, diagnostics)
What is measured
The design makes no latency, memory, or retrieval-quality guarantee (design). Current evidence is a development split, not a held-out result:
- Oracle-assisted navigation replay, 12 tasks: mean file recall at 10 is 0.25 with the old lexical lane, 0.46 with file-first lexical ranking, and 0.63 with CUDA retrieval plus rerank; misses fall from 8 to 6 to 4. (result.json)
- A paired agent trial exists, but most assisted agents misused the wrapper, so it establishes no token-saving or task-success claim. (agent_result.json)
- Indexing has a real cost: about 100 s cold for an 11,620-file repository in a debug build, with an index 17 to 21 times the source bytes. (performance smoke)
The external Codebase-Memory study (roughly tenfold lower token use, 2.1-fold fewer calls) motivates this work; it is not a Trufflepig result.
Get started
cargo install --path . --locked
trufflepig --root . --no-daemon index
trufflepig --root . search 'sym:TokenBucket'
Get started · Design and contracts · Agent setup for Codex, Claude Code, Kimi Code, Muse Code, and omp.
Licensed under GPLv3 only.