afd-oracle
Syncs a repository's GitHub pull requests and issues into the local knowledge base, linking them to commits so they can be surfaced alongside diffs and searched via the search_discussions tool.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
# Oracle
Oracle (afd-oracle) is part of Agentic Fever Dream. It turns a
repository's full git history and code structure into a local knowledge base that Claude Code uses while you work.
It records why code is the way it is, what was tried and abandoned, what secretly changes together, and where the risky
parts are.
It is also a change-safety gate. Before Claude edits code, Oracle shows what the change can break. After the edit, it checks the actual diff for regressions, breaking changes, unintended action at a distance, security hazards, race hazards and logic bombs, and names the tests to run. See Change safety.
It runs entirely on your machine:
Ingestion is deterministic: parsing, diffing, co-change maths, revert detection, metrics and local embeddings. It uses no AI tokens.
Mining runs Claude agents. One agent proposes findings with exact citations, a deterministic gate checks every cited commit, file and symbol against git, and an independent reviewer tries to refute each finding. Only findings that survive become verified insights.
Dashboard (browser) ──► add / update / mine repositories ──► local knowledge base (SQLite + Neo4j + Qdrant)
Claude Code (any repo) ──► afd-oracle MCP server + skill + /afd oracle ──┘New here? The documentation explains how everything works from first principles: ingestion, mining, and every change-safety detector, in short pages that assume no background.
Quick start
Prerequisites: Python 3.12, uv, git, Node.js 18+ (builds the dashboard once), Docker Desktop, and Claude Code for mining and for using the knowledge base.
git clone https://github.com/agentic-fever-dream/afd-oracle.git
cd afd-oracle
uv sync
uv run afd-oracle ui # opens http://127.0.0.1:8765In the dashboard:
Health strip. Click Start services to start Neo4j and Qdrant in Docker and initialise them. Then click Register for Claude and Install skill + commands. These register the
afd-oracleMCP server for your user and install the skill and the/afd oraclecommands into~/.claude. Then click Run at login so the dashboard starts with your session and restarts itself if it ever stops (or runuv run afd-oracle service install).Add repository. Paste a git URL or pick a local folder. Ingestion shows live progress. A first ingest of a large repository can take a while, mostly CPU embeddings. Later updates only read new commits.
Mine. Choose how many candidates to mine. The dashboard shows a token estimate first, then runs the analysts and reviewers through Claude Code in the background, on your Claude subscription.
Insights / Reports. Browse the verified findings with their linked commits and diffs.
uv run afd-oracle setup does step 1's Claude registration from the terminal.
Related MCP server: git-finder-mcp
Using it in Claude Code
Open Claude Code in any repository you have added.
Automatically: the
afd-oracleskill triggers on questions about history and design ("why is this like this?", "was this tried before?", "what else changes with this file?") and before non-trivial edits. Its first step is to callidentify_repo, which recognises the working copy by its root commit or remote URL and reports how stale the knowledge base is.Explicitly: use
/afd oracle <action>:
Command | What it does |
| Before a change: blast radius, coupling, contracts, API, tests, hazards, past fixes |
| After a change: block / warn / pass verdict for the working copy, plus the tests to run |
| Would the tests catch a regression in this function? |
| Sync GitHub pull requests and issues for this repository |
| Answers from the knowledge base, citing insights, commits and paths |
| Is this repository in Oracle, how current is it, top findings, dashboard link |
| Adds this or another repository (deterministic, no AI tokens) |
| Ingests commits added since the last update |
| Mines up to N candidates for verified insights (asks before large runs) |
| Starts the dashboard |
/afd is the shared router for Agentic Fever Dream tools. Each tool installs its action guide into ~/.claude/afd/,
so later tools add /afd <tool> <action> without conflicts.
Change safety
Every ingest runs deterministic detectors over HEAD and the history. They take about 11 seconds on flask, with no AI tokens.
Detector | What it knows |
Test map | Which tests exercise each symbol: static calls, imports, naming, co-change history, and optional per-test coverage ( |
String contracts | Producers and consumers of env vars, config keys, events and signals, HTTP routes and endpoints, SQL tables, registries, feature flags and CLI flags, including orphans |
Typed call graph | Jedi-resolved calls (for example |
Public API | The exported surface at HEAD and recent tags, deprecations, and a classifier for removed or renamed symbols, new required or removed parameters, changed defaults, keyword-only changes and exception changes |
Fix lineage | Fix commits, the guards each added (None checks, raises, locks, bounds, escaping) and their regression tests, which give per-symbol fragility plus security, race and performance zones |
Security | Shell, eval and deserialisation sinks, SQL built from strings, TLS off, autoescape off, path traversal and SSRF from request data, hard-coded secrets, and JS |
Races | Module-level mutable state written from functions, lazy init without a lock, class-level mutables, check-then-act across |
Logic bombs and supply chain | Date- or host-gated behaviour, exec of decoded blobs, dynamic imports, disabled checks and skipped tests, destructive operations, new dependencies, typosquats, install scripts, CI and build hook edits, and opt-in OSV advisories |
Error handling and performance | Swallowed or bare excepts, retry loops, I/O inside loops |
Risk score | Churn × complexity × test gap × fragility × hazards × ownership concentration, per file and per symbol |
Claude uses them through two MCP tools, which the skill calls automatically:
assess_change(paths, symbols)runs before an edit. It returns callers and overrides, hidden co-change partners, shared string contracts, the public API at stake, the tests to run, existing hazards, past fixes and their guards, related verified insights, a risk level, andmust/shoulditems.check_diff(working_dir | diff)runs after an edit and returns ablock/warn/passverdict. It checks for:breaking API changes and guards removed that earlier fixes added
contract producers removed while still used, and new uses of undefined keys
new security, race, logic-bomb and supply-chain findings on the added lines
co-change partners not updated, and changed code no test reaches
It also lists the tests to run.
For risky logic changes, afd-oracle mutate "<file>::<function>" --cwd <repo> --python <project python> measures
whether the tests would catch a regression. It applies targeted mutations, runs the selected tests, and always
restores the file.
GitHub pull requests and issues can be synced per repository: from the dashboard's Risk tab, or with
afd-oracle discussions <repo>. They are linked to commits, returned by get_commit_diff, and searchable with
search_discussions.
The gate is deterministic. It makes risk visible and points to the tests that provide the evidence; it doesn't prove a change is safe.
MCP tools (server afd-oracle)
assess_change, check_diff, list_findings, get_contracts, search_discussions, identify_repo,
repo_overview, search_qdrant (hybrid search over code, commits and verified insights),
get_commit_diff (with authored, committed and landed-on-main dates), get_symbol_history (follows moves and renames),
run_cypher (read-only), list_insights. The mining pipeline also uses get_work_packets, upsert_insight,
verify_citations and set_insight_status.
CLI
uv run afd-oracle <command>:
Command | Purpose |
| Start the dashboard; register the MCP server, skill and commands for Claude |
| Ingest or update a repository |
| Same as the dashboard buttons; streams progress |
| The change-safety gate ( |
| Re-run detectors, import per-test coverage, sync GitHub discussions, targeted mutation testing |
| Inspect and maintain |
| Re-run individual pipeline stages |
Thresholds such as co-change minimums, revert window and abandoned-branch age are AFD_ORACLE_* settings in
packages/afd_oracle_core/afd_oracle_core/config.py. infra/.env (created from infra/.env.example by Start
services) holds the database passwords.
Without Docker
afd-oracle ingest ... --no-graphskips Neo4j. Everything else, including the MCP insight tools, works from the per-repo SQLite store.run_cypherreports that the graph is unreachable.AFD_ORACLE_QDRANT_PATH=data/qdrant-localuses embedded Qdrant. It is single-process only: stop the MCP server whileafd-oracle ingestruns.Any Neo4j 5.x server also works, for example the community zip run with
bin/neo4j consoleon Java 21.
How it fits together
git repo ──pygit2──► history.py ──► SQLite store (data/repos/<id>/store.sqlite) ──► writers/neo4j_writer.py ──► Neo4j
│ ▲ │ embed.py ─────────────► Qdrant
tree-sitter│ │blob-keyed cache ├─ structure / moves / reverts / branches / cochange / metrics
▼ │(parse once, ever) └─ packets.py ──► noise filter ──► work packets ──┐
ast/ extractors ▼
dashboard (afd_oracle_ui) ── headless Claude Code ── .claude/workflows/oracle-*.js ── oracle-analyst / oracle-verifier
│
FastMCP server (afd_oracle_mcp) ◄── Claude Code in your repositoriesPackage | Role |
| Settings, the SQLite store, Neo4j and Qdrant access, embeddings, the citation gate, insights |
| The deterministic pipeline and the |
| The MCP server |
| FastAPI backend, job runner, setup, and the React SPA in |
Store first, project second. The deterministic pipeline writes to a per-repo SQLite store. Neo4j and Qdrant are projections of it. That makes incremental runs cheap and lets the citation gate work offline.
Incremental. New commits are found by hiding previously processed ref tips, and each git blob is parsed once, ever. Derived layers are recomputed on each run, and an incremental run matches a full rebuild (this is tested).
Citation gate (
afd_oracle_core/citations.py):every hash must resolve in the store and in git
every
{path, at_commit}must exist in that tree or diffevery symbol uid must exist
at least one cited commit must have touched a cited file or symbol
It runs again when an insight is marked verified.
Real-history hygiene:
Co-change, reverts and graveyard metrics use main-line commits only.
Deletions and re-creations a few commits apart are linked as moves.
Type-only imports are left out of cycle detection.
Every main-line commit records when it landed.
Packets show authored, committed and landed dates separately, and flag pure renames.
Noise filter (
AFD_ORACLE_PACKET_NOISE_FILTER, on by default). It drops candidates a program can recognise as noise:docs-only, trivial, version-bump and dependency-bump changes
tests changing alongside the code they test
docs or changelog lockstep
pairs already linked by an import
duplicate PR refs and branches with no source change
moved symbols and test code
Drops are counted by reason. On the flask repository this cut 2,382 candidates to 899.
Mining runs headless. The dashboard (or
afd-oracle mine) claims candidates, writes a run file, and startsclaude -pin this folder to run theoracle-fullworkflow. Candidates are marked done when the run succeeds; a failed run's candidates can be released back to the queue.Insights go
proposed→verified|rejected. They are stored in SQLite, projected to Neo4j (:Insight:AntiPatternand so on,EVIDENCED_BY,CONCERNS), and embedded intoarchitectural_insightsonce verified. If Neo4j was down,afd-oracle sync-insightsreplays them.
Design notes
Extractors walk tree-sitter nodes directly instead of using
.scmquery files. The py-tree-sitter query API changed across 0.2x releases, while node and field traversal stayed stable.Neo4j Community has no role-based access control, so
run_cypheruses READ-mode transactions (enforced by the server), a clause guard, and row and time limits.Verification. Medium- and high-severity findings get an Opus reviewer (two for high severity). Info and low findings get a Sonnet reviewer. If a reviewer fails, the insight stays
proposed.Commit identity is repo-scoped (
commit:<repo>:<sha>), so a fork and its upstream can both be ingested.The dashboard binds to 127.0.0.1 only. Every request that changes something must carry an
X-AFD-Oracle-UIheader, which blocks cross-site requests.
Tests
uv run pytest tests --ignore=tests/mcp && uv run pytest tests/mcp # ~320 tests; Neo4j tests skip unless AFD_ORACLE_NEO4J_PASSWORD is set and a server is on :7687
cd packages/afd_oracle_ui/web && npm run build # type-checks and builds the dashboardThe suite builds a fixture repository with planted facts and checks:
History: counts against
git rev-listandgit show --numstat, lifecycle events, a full cache hit on re-run, and an incremental run matching a full rebuild.Analysis: Jaccard against
git log, both kinds of revert, branch classification, the import cycle, the god class, the noise filter, cross-commit moves and landing dates.Guardrails: MCP guards, the citation gate, the insight lifecycle, and
identify_repoon working copies and clones.Dashboard API: add, ingest, estimate, mine (with a stand-in for
claude) and release.
Tests use a hash embedder and in-memory Qdrant, so they never download models.
CI and releases
CI (
.github/workflows/ci.yml, every push and pull request): a gitleaks secret scan over the whole history (rules in.gitleaks.toml), the test suite on Windows, and the dashboard type-check and build.Release (
.github/workflows/release.yml): push a tag matching the version, e.g.v0.1.0. It re-runs the secret scan, builds the dashboard and every package's wheel and sdist (uv build --all-packages), signs each file, writesSHA256SUMS, adds a build-provenance attestation and publishes a GitHub release. Run it by hand for a dry run that stops before publishing.Signing: the release signs with a PKCS#12 certificate held in the
SIGNING_CERTsecret (base64 of the.pfx) andSIGNING_CERT_PASSWORD. Each artifact gets a detached CMS signature (.p7s) and the release carriessigning-cert.pem; verify withopenssl cms -verify -binary -inform DER -in file.whl.p7s -content file.whl -CAfile <issuer chain>. Without the secret, releases are published unsigned with a warning.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides semantic code intelligence to help users search, navigate, and analyze entire codebases using plain English. It enables Claude to perform architectural overviews, bug detection, and refactor suggestions through local semantic search and keyword indexing.MIT
- FlicenseAqualityDmaintenanceEnables natural language code search across multiple local Git repositories, allowing users to register projects, search for code, and explore file structures through Claude.6-
- AlicenseNot gradedqualityBmaintenanceEnables private source-code repositories to be indexed and searched via hybrid retrieval (symbol, lexical, semantic, and code-graph), then packages token-budgeted, structure-aware context for LLMs such as Claude.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code to query a local, import-aware graph of a repository, so questions like who calls a function, what breaks if it changes, and what imports a file are answered in one lookup instead of a search-and-read loop. It also persists durable session notes and offers full-text search over past session transcripts, all through MCP tools.30 PyPIMIT