Hunch

Your repo remembers why — and teaches every coding agent how the project works.

Every new AI coding session can read your code. It cannot automatically see why your team chose this design, which alternative already failed, what an odd-looking line protects, or how this repository expects work to be explained and reviewed.

That is how settled decisions get reopened, fixed bugs return, and technically plausible changes arrive feeling foreign to the project.

Hunch is evidence-backed deterministic project intelligence for the AI coding tools you already use. It gives Claude, Codex, Cursor, Copilot, Windsurf, Antigravity and other MCP clients the same durable understanding of your codebase:

• why the code is shaped this way;
• how the repository communicates, reviews and builds;
• what depends on the code about to change; and
• which trusted decisions, fixes and architectural boundaries the result must preserve.

For precise rules your team has explicitly trusted, the promise is Never Twice: an agent may propose a different direction, but it cannot quietly re-make a decided decision or re-introduce a fixed failure without Hunch surfacing the conflict and its evidence.

Memory starts advisory. Nothing blocks until a human deliberately trusts a precise rule and opts into strict enforcement.

Start in five minutes

Requires Node 22.13+ and a Git repository.

npm i -g @davesheffer/hunch
cd your-repo
hunch init
hunch backfill --since 90d   # optional: seed memory from recent history

Reload your coding assistant, then ask a normal question:

Why is this built this way?

hunch init indexes the repository, installs local lifecycle hooks and connects supported assistants without replacing their existing configuration. The next session receives the relevant story with its sources, not a giant transcript or generic prompt wall.

Lifecycle coverage depends on the harness; MCP connectivity alone does not establish automatic grounding or enforcement.

To update Hunch and configured harness pins for the current repository:

hunch update

Agents receive an instruction to run this when you ask “update Hunch” in generated Hunch guidance. Restart active harnesses afterward.

Check integrations after upgrading Hunch or switching assistants:

hunch integrations check
hunch integrations repair-pins
hunch integrations check --harness claude --probe --require mcp
hunch integrations check --harness codex --require context,edit-blocking

Capabilities are reported as verified, advisory-only, unsupported or untested. --require fails unless every named capability is verified.

The Codex integration currently supplies MCP and instructions, with no native lifecycle adapter. The opt-in --probe verifies a fresh MCP process, not whether an existing host session or model actually followed the memory.

Use hunch integrations check in CI to prevent pin drift; add --require for capabilities your workflow cannot operate without.

One evidence loop, not another model

Git history + ADRs + corrections + tests + repository conventions
                              │
                              ▼
                  Hunch's evidence graph
                 /            │             \
      engineering memory   Project DNA   reviewed landscape
                 \            │             /
                              ▼
             role-shaped, budgeted context delivery
                              │
                              ▼
             Claude / Codex / Cursor / any MCP agent
                              │
                              ▼
                  deterministic change receipt

Hunch is not the agent and is not the workflow engine. The model thinks; Hunch holds deterministic, evidence-backed state about the project and validates what must remain true.

What Hunch understands

Readable JSON in .hunch/ is the repository-scoped source of truth. SQLite is a fast, rebuildable projection. Git keeps the state portable, reviewable and reversible.

Project DNA: help the agent work like it belongs here

Project DNA is Hunch's evidence-bound model of how a repository communicates and works. It is not a persona, does not impersonate a maintainer and does not turn frequent behavior into policy.

The deterministic baseline reads an exact Git revision, bounded commit history and committed convention files. The current release can also accept bounded, caller-authorized pull-request/review evidence. Every evidence batch is validated and sealed; raw collaboration text does not enter the profile.

Each trait keeps its category, confidence, freshness, repository revision and evidence hash. Hunch can include only the relevant DNA in normal context, explain how an artifact matches repository conventions and show profile change between revisions.

hunch dna inspect
hunch dna context
hunch dna diff <older-ref> <newer-ref>

DNA may shape orientation, terminology and advisory Project Match checks. It cannot create or override a decision, constraint, finding, conformance rule, policy or permission.

Read the Project DNA contract and broader Project DNA vision.

Day-to-day

When you are ready for deterministic enforcement:

hunch firmness strict
hunch check --staged --strict

Captured memory cannot silently hard-block on its own.

Deterministic organizational state — next product direction

Repository memory solves one version of a larger problem.

As organizations give every employee an agent that can work across CRM, email, messaging, repositories and other tools, the agents become probabilistic writers/readers of the same organization. If each one independently reconstructs what was decided, what was already done or what is still owed, the organization gets multiple conflicting realities.

The active roadmap asks whether Hunch can become the deterministic state layer between those agents and the organization:

Agents are probabilistic. Organizations need deterministic state. Hunch is the state layer between them.

The target is one product, one authorized state graph and one versioned state contract across repository, user, team and organization scopes.

Planned state includes:

• decisions currently in force;
• verified action receipts / what was done;
• commitments and due-state;
• entities and relationships;
• code/system changes with proof;
• repository/user/team/org DNA;
• derived current state with exact dependencies/invalidation.

Agents continue to own live connector mechanics. Hunch must not become a managed proxy that fetches Gmail, CRM, WhatsApp or GitHub on an agent's behalf.

Instead:

                  Hunch deterministic state
                        ↑       ↓
agent -> deterministic action gate -> connector -> source system