Inspiration

Coding agents edit the file they were asked about and miss the test, the changelog, or the sibling module that always moves with it. That knowledge is already in git history, but it is a relationship question — "what changes when this changes, and who knows it?" — which grep and embeddings answer poorly. It is exactly what a graph is for.

What it does

Ripple loads a repository's git history into a Relate store (one .ripple.rl file) and answers three questions, locally, with no server:

  • ripple context <file> — files that usually change with it (with directional confidence), the people who know it, and its recent commits.
  • ripple check — given a diff (--staged, working tree, or a list), files that are historically coupled to the change but missing from it. --strict exits 1, so it works as a pre-commit hook or CI gate.
  • ripple hotspots — most-changed live files and how coupled they are. Every command has --json, and skill/SKILL.md is a drop-in skill that tells Claude Code, Cursor or Codex to call context before editing and check --staged before committing. The live explorer (GitHub Pages) shows the same graph for the full pallets/flask history.

How we built it

  • Graph model: (:Commit)-[:TOUCHED {added,deleted}]->(:File), (:Commit)-[:AUTHORED_BY]->(:Author), and a materialised (:File)-[:CO_CHANGES {n, conf_ab, conf_ba}]->(:File).
  • Ingest: git log --no-merges --numstat → batched Cypher UNWIND … MERGE through relate-db (Python). Flask's 3,817 commits load in ~1.3 s.
  • A single Cypher pass computes co-change pairs and their directional confidence; commits touching >40 files are skipped as noise; files absent at HEAD are marked non-live and hidden from answers.
  • context/check/hotspots are graph traversals; ripple export writes the JSON the static explorer reads, so every number on the site comes from Cypher against the store.
  • A persistent store judges can inspect is checked in: examples/flask.ripple.rl.

Challenges we ran into

Directional confidence matters: CHANGES.rst changes with almost everything, but most files don't change with CHANGES.rst. Storing both directions on one edge kept queries simple. Bulk commits and renamed paths needed filtering so answers stay useful.

Accomplishments that we're proud of

It works end to end on a real, long-lived project from a clean clone in seconds, with one file and no infrastructure — which is what makes it practical for agents.

What we learned

Embedded graphs fit agent tooling well: the agent gets relationship answers in-process and the whole context is a file it can carry between sessions or share between agents.

What's next for Ripple

Follow renames, mailmap identities, an MCP tool over the same store, and weighting recent history higher.

Share this project:

Updates

Submission history