Paste a pull request. Staleproof follows the changed code through a FalkorDB graph of every repository you own — code, docs and the decisions your maintainers made — to the paragraphs it can make false. It runs those examples before and after the change, and proposes the docs fix with the evidence behind each edit.
npx -y staleproof check https://github.com/FalkorDB/falkordb-py/pull/262Is_Clusterfalkordb-pyFalkorDB.__init__falkordb-pyREADME · Asynchronous Examplefalkordb-pyTypeError: Redis.__init__() got an unexpected keyword argument 'himport_registry'exit 0 The README's async example was broken until this PR fixed it. A name search finds nothing: no doc mentions Is_Cluster. The call graph does.
The path ExecutionPlan._operation_tree ← ExecutionPlan.__init__ ← Graph.explain led into a different repository: the docs site's GRAPH.EXPLAIN page. Its example fails on a fresh server before and after the PR — it explains a query on a graph the page never creates. Not caused by the PR; already broken, and now known.
They reach 43 doc sections through paths like AsyncGraph.query ← FalkorDBConnection.query (GraphRAG-SDK) ← … ← GraphRAG-SDK README. Of the 21 examples run at both commits, 10 pass both times, 6 were already broken, 3 can't be installed together at those commits (version skew) and 2 can't run as written.
Paste a pull request from any public Python, TypeScript or JavaScript repository on GitHub: the first check indexes it, in seconds for most projects. Or pick one of FalkorDB's. The trace streams every tool call and the Cypher it ran on FalkorDB.
A model chooses which tools to call, reads each affected section, and writes a verdict or an edit for every one of them.
The same tools in a fixed order with no model and no API key: impact, clearance, ranking, and a sample of up to three example runs. Deterministic and free.
The interactive demo needs JavaScript. These are the pull requests it opens with:
A change to the client breaks a tutorial in the SDK and a page on the docs site. Code review only sees the repository the PR is in.
The README calls FalkorDB(), whose constructor calls the function you changed. The docs never name that function, so search finds nothing.
Tutorials are code that never runs in CI. They break silently, and readers find out first.
Each step is a tool that runs Cypher on FalkorDB and returns the queries it ran. The agent decides the order; graph mode runs them in a fixed one.
Clone your repositories into one graph: Python and TypeScript functions and the calls between them across repositories, every docs section and code example (Markdown, MDX or Sphinx), and the code each one mentions or calls — with every call checked against the signature it reaches.
From each function the PR changed, walk back up to three callers, in any repository, to the docs that mention or run them.
Evidence path: the chain from the changed function to the paragraph — the reason it is flagged, shown for every hit.
Changed functions that no doc reaches within three calls are listed as cleared, with the grep a reviewer can run to double-check.
Clearance: a proof of absence: the graph shows no path from the change to any doc, so you can skip it with confidence.
Run each affected example at the commit before the PR and at the PR, in a sandbox. Passes before, fails after: the PR broke it. Fails both: it was already broken.
Every affected section ends with a verdict. Edits are refused without a graph path, and come out as a git apply-able docs patch with the evidence per section.
Verdict: stale (with the edit), ok, governed by a maintainer decision, or skipped — always with the reason.
Verdicts, example runs and maintainers' decisions are written back to the graph. The next PR reads them before judging.
Verdict memory: a decision like "keep the old kwargs until 2.0" is cited instead of being re-flagged on every PR.
"Which paragraphs, in which repositories, can this change make false?" is reachability over call edges that cross repositories. It is one Cypher pattern, and on FalkorDB it answers in about a millisecond.
The graph model and every queryMATCH (pr:PullRequest {url: $pr})<-[c:CHANGED_IN]-(s:Symbol)
WHERE c.kind <> 'added'
MATCH p = (s)<-[:CALLS*0..3]-(t:Symbol)<-[:MENTIONS|USES]-(d)
WHERE (d:DocSection OR d:CodeExample) AND d.status = 'live'
RETURN d.id, length(p) AS hops,
[n IN nodes(p) | coalesce(n.qualname, n.id)] AS evidenceYour client, the SDK built on it and the docs site live in three repositories. One graph spans them, so a change in the client surfaces the pages in the other two.
On falkordb-py#276, 41 of the 43 reachable sections were in other repositories.
Check every merged pull request, rank the affected sections by PageRank over your docs' own links, and ship one patch with the evidence for each edit.
Each PR gets a comment listing the docs it can falsify, the path for each, and the changed functions no doc reaches. Graph mode needs no LLM key.
Over MCP, your coding agent asks which docs depend on a function before changing it (docs_for_symbol), which examples its edits break before anything is pushed (check_changes), and produces the docs patch.
An audit checks every call in every example against the current code, across repositories, scores the docs and lists the public API no page covers. Weekly in the Action, with one issue kept up to date.
On FalkorDB's docs it finds client.create_constraint, a method FalkorDB doesn't have; on Flask's, as_view() without its required name.
Each organisation gets its own graph on the same FalkorDB. Serve the API to your tools, or embed the library in your own pipeline.
A second graph from encode/httpx runs next to FalkorDB's on the same server.
Setup, commands and what to expect for each scenario.
Use cases in the docsCall edges are resolved across repositories through imports, re-exports, attribute types and return annotations.
Examples run at both commits in a sandbox, so "this PR broke it" is a test result, not a guess.
Each flagged section carries the path that reached it. No path, no edit: the tool refuses.
Clearance lists changed functions no doc reaches, so reviewers know what they can skip.
Maintainer decisions and past verdicts are cited on the next PR instead of re-flagged.
PageRank over your docs' links orders the work, so the page readers land on gets fixed first.
Agent mode uses Claude or any Anthropic-compatible API; graph mode needs no key at all.
Every result lists the Cypher it ran and how long it took. Nothing is hidden behind a score.
One npm package, five ways in, and two ways to host it. Everything runs against your own FalkorDB.
No install and no Docker: the first check starts FalkorDB locally from a Python wheel and indexes the repository (--with adds a docs repository). Add ANTHROPIC_API_KEY for agent mode, or pass --no-agent.
$ npx -y staleproof check https://github.com/FalkorDB/falkordb-py/pull/262 --no-agent
# an organisation's repositories in one graph, then the docs patch
$ npx -y staleproof index FalkorDB/falkordb-py FalkorDB/GraphRAG-SDK FalkorDB/docs
$ npx -y staleproof check https://github.com/FalkorDB/falkordb-py/pull/262
$ npx -y staleproof patch https://github.com/FalkorDB/falkordb-py/pull/262No inputs and no secrets: the job starts its own FalkorDB, indexes the repository, runs the affected examples before and after, and posts (or updates) one comment. The install page commits this file for you.
Read the GitHub Action guideon:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: rajkaria/staleproof@v1The hosted MCP server needs nothing installed and indexes any public repository on first use; one-click buttons are on the install page. Every tool description includes its Cypher, and every result lists the queries it ran.
Read the AI assistants (MCP) guide# hosted: nothing to install
$ claude mcp add --transport http staleproof https://staleproof.dev/api/mcp
# or local, with example runs
$ claude mcp add staleproof -- npx -y staleproof mcp
# then ask:
> Which docs can https://github.com/FalkorDB/falkordb-py/pull/262 make false? Show the evidence path for each.serve runs this web app and its JSON API. A check streams every tool call and result as it happens, then stays stored on the graph.
$ npx -y staleproof serve --port 8080
$ curl -N localhost:8080/api/check \
-H 'content-type: application/json' \
-d '{"pr_url": "https://github.com/FalkorDB/falkordb-py/pull/262", "mode": "graph"}'The package exports the indexer, the tools, both check modes, the patch builder, the MCP server and the HTTP app.
Read the Node.js library guideimport { GraphStore, loadConfig, runGraphCheck } from 'staleproof';
const config = loadConfig();
const store = await GraphStore.connect(config.falkordbUrl);
const check = await runGraphCheck({ graph: store.org(config.org), config }, 'https://github.com/FalkorDB/falkordb-py/pull/262');
console.log(check.status, check.summary);
await store.close();The live demo runs as a Vercel Function against FalkorDB Cloud's free tier. A Docker Compose file runs the app with its graph and a scratch database.
The Vercel deployment is live; the Docker image is written but has not been built yet.
Read the Self-host guide# Vercel: point the function at your FalkorDB, then deploy
$ vercel env add FALKORDB_URL production
$ vercel deploy --prod
# Any VM
$ docker compose up -d --buildBoth find text. The question here is reachability, and whether the example still runs.
| grep / code search | Vector search over docs | Staleproof | |
|---|---|---|---|
| Finds docs that reach the change through other functions | No — only the names you search for | No — similarity, not reachability | Yes — up to 3 call hops, in any repository |
| Proves a change broke an example | No | No | Yes — runs it before and after |
| Proves a change touches no docs | No — no match is not proof | No | Yes — clearance over the graph |
| Says why a paragraph is flagged | The matching line | A similarity score | The evidence path |
| Remembers what maintainers decided | No | No | Yes — decisions and verdicts on the graph |
| Noise on FalkorDB’s 4 checked PRs | 227 unrelated matches | — | Only sections the change reaches |
The documentation is published as Markdown next to the site, so an LLM gets the same facts you do — without scraping a JavaScript app.
/llms.txtA one-page map of the docs in the llms.txt format, with quick facts for assistants.
/llms-full.txtEvery docs page in one plain-text file, ready to paste into a context window.
/docs/<page>.mdEach docs page as raw Markdown. Every page also has a "Copy as Markdown" button.
MCP tool descriptionsEach tool tells the model what it does and the Cypher it runs; each result lists the queries it ran.
Code: Python, TypeScript and JavaScript (tree-sitter), across repositories. Docs: Markdown, MDX and reStructuredText (Sphinx), in any repository. Python examples are run before and after a pull request; JavaScript and TypeScript examples are linked and checked statically, not run.
No. Audit any public repository to see which examples no longer fit the code today, npx -y staleproof check with no pull request checks your working tree before you push, and docs-for lists the docs that depend on a function before you change it.
No. Graph mode runs impact, clearance, PageRank ranking and up to three example runs with no model. Agent mode adds a model that reads each section and writes the verdicts and edits; it needs ANTHROPIC_API_KEY.
Claude by default (claude-sonnet-5-5), or any Anthropic-compatible API through ANTHROPIC_BASE_URL. The live demo runs deepseek-v4-pro through DeepSeek's Anthropic-compatible endpoint.
No. It proposes edits; patch prints a git apply-able diff, and patch --open-pr opens it in your fork only when you ask (--upstream targets the original repository).
Each example runs with no inherited secrets, a temporary HOME and a timeout, and its outbound connections are refused except a disposable scratch FalkorDB. The install step that builds the repositories at the PR's commits gets only an allow-listed environment, so PR build code never sees your credentials. It is a guard, not a security boundary: for untrusted code, run it in a container.
With the CLI or the GitHub Action, indexing, the graph and example runs stay wherever you run them, and private repositories work with a token. In agent mode, tool results (doc text, signatures, run output) go to the model provider you configure; graph mode sends nothing to a model. The hosted site and MCP server index public repositories only.
Nothing: it is MIT licensed. You run FalkorDB (locally, in Docker, or on FalkorDB Cloud's free tier) and pay your model provider in agent mode.
Impact is a variable-length path across repositories, clearance is the same pattern negated, decisions govern code transitively, and ranking is PageRank. Take FalkorDB out and it is a grep over one repository.
More in Troubleshooting and FAQ.
Add the workflow once; every pull request after that gets its docs impact, with proof.