Twiceshy

What is Twiceshy?

A self‑hosted service that feeds hard‑won engineering experience — issues, dead‑ends, root causes, validated fixes — to LLM coding agents at decision time, so they stop repeating known mistakes on autopilot. It operates like a private, curated, validated StackOverflow that injects itself at the right moment.

How to use Twiceshy?

Use the hosted instance at twiceshy.app with the remote MCP endpoint https://api.twiceshy.app/, or self‑host following the development instructions (make ci). Interact via MCP tools: search_experience, get_experience (read path) and record_experience (propose‑only write path).

Key features of Twiceshy

• Git‑backed markdown experience records with YAML frontmatter.
• Derived SQLite index with FTS5 (dense retrieval planned).
• Multi‑stage retrieval: fingerprint‑exact → BM25 → dense, with relevance floor and hard cap of 3 results.
• Two channels: push (Claude Code hooks) and pull (MCP tools over streamable HTTP).
• Trust model: agent‑proposed records quarantined, promoted only after sandbox validation and human PR review.
• Background “doctors” for dedup, staleness, repro re‑execution, decay, and abstraction.

Use cases of Twiceshy

• Prevent an agent from re‑introducing a known bug or deprecated API.
• Inject verified workarounds for third‑party issues at decision time.
• Record and propagate root‑cause analyses across a team.
• Capture validated fixes so future agents skip dead‑end investigations.
• Automatically quarantine untested proposals until they pass human review.

FAQ from Twiceshy

What retrieval stages does Twiceshy use?

Retrieval follows a cascade: fingerprint‑exact → BM25 → dense (RRF), with stack‑fingerprint filtering and a relevance floor. At most 3 results are injected; below the floor nothing is injected.

How does Twiceshy ensure experience records are trustworthy?

Agent‑proposed records are quarantined. Promotion requires a sandbox fail‑to‑pass validation and a human‑reviewed pull request. A new record is a PR.

What is the license?

The Twiceshy engine is AGPL‑3.0‑only. Contributions require a signed CLA, and the corpus has a separate licensing strategy (see ADR‑0002).

What is the current status of development?

Bootstrapping. Phase 1 (read path: parser/validator, FTS5 index, fingerprint + lexical search, MCP search_experience/get_experience) is complete. Phase 3 write path (record_experience – propose‑only) has landed. Remaining phases (hooks push channel, dense retrieval, doctors) are tracked as issues.