Ripplet

A precise, local code graph for coding agents. Ripplet indexes a repository into a call / type / data graph and answers the questions agents otherwise answer with grep: who calls this, what breaks if it changes, which lines a rename touches, which tests to run. Every answer comes with file:line, and a link the graph cannot prove is labelled as such instead of being guessed.

• Precise. Checked call by call against compiler-grade indexes (SCIP): zero wrong edges across 12 repositories, 0.92 call-site recall.

• Built for agents. MCP server, always-on rules for Claude Code, Codex, Gemini CLI, Cursor, Copilot, OpenCode and more, a Claude Code skill, and hooks that steer an agent to the graph before it greps.

• Change safety. Impact of an edit, a dry-run rename, broken callers after an edit, the exact tests that reach a change, PR review, architecture rules.

• Local. One SQLite file, no LLM, no cloud, no vector database. Python 3.12+.

pip install "ripplet[treesitter-multilang]"
ripplet setup .        # index + MCP config + agent rules/skill/hooks, in one step
ripplet ui .           # browse the graph

At a glance

Details and per-repository numbers below.

How it compares

Measured on real open-source repositories with harnesses that score every tool the same way (ground truth: textual call sites, the files real commits changed, or mutants a test suite kills). Graphify 0.9.92 was run with its defaults (graphify extract --code-only, graphify query).

Finding every caller of a function

Site recall = share of the real call sites (file:line) the tool reports.

Per language, all three sets: Java 99% vs 66%, TypeScript 91% vs 14%, Python 96% vs 29%, Go 98% vs 48%, C# 93% vs 11%, Lua 94% vs 6%, Rust 90% vs 56%, Ruby 86% vs 25%, PHP 100% vs 79%.

Finding where a task should be done

The commit subject of a real later commit is the task; the files that commit changed are the answer. task_context vs graphify query.

hit@1 = the first file named is one the commit changed; hit@5 = one of the first five. 389 tasks on 13 repositories (Python, Java, Go, TypeScript, PHP); the last 9 were added later as hold-out sets, to catch tuning that only fits the first four.

Average answer size: about 1,500 tokens.

Picking the tests to run after a change

Mutation test selection: a mutant is caught when one of the selected tests fails on it.

Ripplet selects the tests that reach the changed symbol through calls, instantiation and inheritance, so a broken change is far more likely to fail a selected test; it also selects more tests (43% of click's suite, 16% of conduit's).

Precision against a compiler

Ripplet's call edges compared with SCIP indexes (scip-typescript, scip-python, rust-analyzer, scip-go, scip-dotnet, scip-java) — every call site the compiler resolves, and every edge Ripplet claims:

A call Ripplet cannot prove (an untyped receiver whose method name exists in the project) is not turned into an edge. Agents see it in an UNVERIFIED section: possible caller, check the line.

With a coding agent

Claude Haiku 4.5, headless, 13 repositories in 13 languages; the same tasks with and without Ripplet (without = no MCP server, no rules, no hooks).

Renames are as reliable at less than half the cost and a fifth of the turns. Caller lists are about as complete; where the graph has a gap, the agent is told so (UNVERIFIED) rather than given a confident wrong answer.

Related MCP server: codegraph-mcp

Languages

Deep analysis (symbols, imports, calls with receiver types, inheritance, overrides) for:

Also indexed: SQL schemas and code migrations (Laravel, Rails, Django, Alembic, EF Core, Prisma) as tables and columns, HTTP routes and the client calls that hit them across languages, Docker Compose, Kubernetes, CI workflows, Terraform, Markdown docs, config files.

Using it with agents

ripplet setup .                 # init, index, .mcp.json / opencode.json, rules, skill, hooks, guard
ripplet rules on . --target all # rules for every agent below
ripplet rules on . --strict     # block the first raw read/grep until a Ripplet tool is used

This repository ships the same guidance as files you can copy: CLAUDE.md, AGENTS.md, GEMINI.md and the Claude Code skill skills/ripplet/SKILL.md.

MCP tools

ripplet mcp serves these over stdio (ripplet tool <name> key=value runs any of them from the shell):

Answers fit a token budget and say how to get more; read tools re-index changed files first, so line numbers follow the agent's edits.

Change safety from the command line

ripplet impact --symbol Store.save                  # what depends on it
ripplet tool change_plan symbol=Store.save change=rename new_name=persist
ripplet check . --run-tests                         # broken callers + the tests that reach the change
ripplet review . --base origin/main                 # PR review (Markdown or --format sarif)
ripplet arch                                        # architecture rules in ripplet.arch.yaml
ripplet test-plan --working-tree                    # tests to run, with the evidence for each

Architecture rules are checked on the graph, not on text:

rules:
  - id: writes-need-permission
    must_call: [requireRole, requireNotViewer]
    for: {path: "app/Controllers/*.php", type: [method], public: true, name: "^(store|update|delete)"}
    depth: 3
  - id: ui-not-db
    forbid: {from: "src/ui/**", to: "src/db/**"}

The UI

ripplet ui . opens a local, read-only explorer:

• Map of module dependencies, Explore a symbol's neighbourhood (graph or list, large neighbourhoods grouped by file), Impact ring by ring with the tests that reach it, Changes of your working tree, Path between two symbols.

• Routes with their handlers, Data: tables, columns and the queries on them (SELECT / INSERT / UPDATE / DELETE), Index health: coverage per language, stale files, agent setup.

• Every caller with the call's code, proven vs inferred links, possible (unverified) callers, and a dry-run rename preview.

Install

pip install ripplet                              # Python, Markdown, config, SQL
pip install "ripplet[treesitter-multilang]"      # + every language above
pip install "ripplet[watch]"                     # ripplet watch: re-index on save

ripplet index .                 # build / update the graph (incremental)
ripplet search Store            # find symbols
ripplet explain Store.save      # source, callers, callees
ripplet status                  # what is indexed

Optional local semantic search with Ollama (ripplet embed --model qwen3-embedding:0.6b, then ripplet query ... --mode hybrid_full); everything else works without a model.

Limitations

• Static analysis: calls made through reflection, string-built names or dependency injection containers configured at runtime are not followed (Laravel's app(X::class) is).

• Dynamic languages (Ruby, Lua, PHP without types) have more UNVERIFIED sites than typed ones; Ripplet reports them instead of guessing.

• Generated code that only exists after a build is not indexed.

• Single SQLite file per workspace.

License

Ripplet is source-available under the Functional Source License 1.1, Apache 2.0 future license (FSL-1.1-ALv2).

• Free to use for anything except a competing product: personal projects, work, commercial companies, internal tools, CI, education, research.

• Free to change, and to share your changes, as long as the license and copyright notices stay.

• Not allowed: offering Ripplet, or a copy or fork of it, as a commercial product or service that competes with it.

• Becomes Apache 2.0 two years after each release.

• The name "Ripplet" and its logo are trademarks and are not licensed.

For a commercial or team license, contact the author.

Support

Ripplet is built by one person. If it saved you a few greps (or a broken release), you can buy me a coffee.

Author

Mehmet Emin Madanoglu