-> TL;DR HandoffGraph loads a repository's Git history into FalkorDB, then an agent walks the graph to answer "what breaks if this person leaves, and who can take over?" Every answer comes with the Cypher it ran and a live subgraph. The agent then acts: it writes a hand-off plan.
💻 Code: [github.com/KomalDeep355/HandoffGraph]
HandoffGraph
An agent that finds the files only one person understands, and plans the hand-off before that person leaves.
HandoffGraph loads a repository's Git history into FalkorDB as a knowledge graph of contributors, files and modules. An agent then calls graph tools to answer questions such as which modules depend on one person, what is orphaned if they leave, and who should inherit it. It acts on the answer by writing a hand-off plan. Every answer ships with the Cypher that ran and the subgraph that justified it.
- Live demo: https://handoffgraph.onrender.com/
- Blog post: https://dev.to/komal_deep_355/what-breaks-when-your-best-engineer-leaves-i-asked-a-graph-4khg
- Video link: https://youtu.be/zoFgDCOhXvQ
The problem
Important knowledge in a codebase often sits with one person. A module may have a single recent author, or a file may have no active alternative owner. When that person is unavailable, the team finds out the hard way. Static CODEOWNERS files don't show who has actually worked…
🌐 Live demo: https://handoffgraph.onrender.com
Where the idea came from
It started with an Instagram reel. I don't remember the names and I can't verify the story, but the gist stuck with me: a company's code depended almost entirely on one developer, because he was the only person who really understood what it was doing. When he left, the team was stuck enough that they had to call him back.
It was told as a joke, and it's funny until it happens to your team. It made me wonder whether you could spot that risk before someone leaves, using the history your repository already has.
The question nobody can answer quickly
Imagine your most experienced maintainer announces a long break, starting Monday.
Which parts of the codebase can nobody else touch?
On most teams the honest answer is a shrug. A CODEOWNERS file tells you who is listed, not who has actually worked on a file recently, and it says nothing about whether anyone else could pick it up. This is key-person risk, better known as the bus factor, and the evidence for it is already sitting in your repository history.
The idea: Git history is already a graph
Every commit says this person changed these files at this time. Add the module each file lives in, and which files tend to change together, and you have a network:
(Contributor) --TOUCHED--> (File) --IN_MODULE--> (Module)
| |
| CO_CHANGED (files that change together)
|
COLLABORATES --> (Contributor)
Asking "what breaks if X leaves?" means following those edges: from a person to their files, from those files to other active people, and from the files up to their modules. That is a traversal. In a relational table, each new follow-up question is more joins and more glue code.
Does the graph really do the work?
The hackathon brief says the graph has to shape what the agent does, not sit on the side. In HandoffGraph, the agent knows nothing about the repository except what FalkorDB returns. Take the database away and every tool has nothing to say.
| The agent needs to decide... | FalkorDB feature it uses |
|---|---|
| Which modules are fragile |
KNOWS edges aggregated from TOUCHED
|
| What is orphaned if X leaves | Multi-hop OPTIONAL MATCH, restricted to active peers |
| Who should take over |
CO_CHANGED proximity plus direct ownership |
| Why it reached a conclusion |
shortestPath from person to module |
| Who the hubs are |
algo.pageRank on COLLABORATES
|
| Keeping repos separate | One graph per repository (multi-graph) |
An honest note on the split: traversals and aggregations run in Cypher. The last bit of ranking arithmetic, like "how many people cover 50% of the knowledge", runs in Python on the rows Cypher returns.
Three queries that carry the project
1. The orphan check. Start at a person, walk to every file they touched, and look for other active contributors on the same files. Files with no real backup are the risk.
MATCH (p:Contributor {id:$id})-[t:TOUCHED]->(f:File)
OPTIONAL MATCH (f)<-[o:TOUCHED]-(q:Contributor)
WHERE q.id <> $id AND q.active = true
WITH f, t.score AS mine, coalesce(sum(o.score), 0) AS others, count(q) AS active_peers
WHERE mine >= 0.75 AND others <= 0.25 * mine
RETURN f.path, f.module, mine, others, active_peers
ORDER BY mine DESC
2. The explanation. Instead of "trust me", the agent can return the actual chain of evidence:
MATCH (a:Contributor {id:$id}), (m:Module {name:$m})
RETURN shortestPath((a)-[:TOUCHED|IN_MODULE*..3]->(m))
3. The hubs. Graph algorithms as agent tools, not code the agent has to write:
CALL algo.pageRank('Contributor', 'COLLABORATES') YIELD node, score
RETURN node.name, node.active, score
ORDER BY score DESC LIMIT 6
Successor ranking (direct recent work plus CO_CHANGED proximity) and module risk are in the README.
What I found on a real repository
I loaded the public history of fastapi/fastapi (source files under fastapi/ only): 855 commits, 209 contributors, 59 files, 7 modules.
- 6 of the 7 modules have a bus factor of 1 under my heuristic.
- One contributor holds about 80% of the recent-weighted knowledge in the core package.
- 17 files across modules have no other active contributor with comparable recent history.
- The agent explains the link with a path such as
Person → fastapi/__init__.py → fastapi/(core).
I want to be careful here. That is a statement about commit history, not about the project's health. FastAPI has many maintainers and reviewers, and review work, triage and design discussion don't show up in commits. I chose a well-known public repo because anyone can verify it, not because I think it is at risk.
From insight to action
Track 01 is about agents that act on what the graph shows. Ask for a hand-off plan and the agent:
- runs the leave-impact query for that person,
- finds successors for the most affected modules,
- writes a Markdown plan, like this:
## fastapi/(core) (80% of module knowledge, 7/26 files orphaned)
- Suggested mentee: **<top-ranked active contributor>** (backup: <next candidate>)
- Pair-review these files first: `fastapi/routing.py`, `fastapi/params.py`, ...
It can also draft GitHub issues. Those are a dry run unless you set a token, point it at your own sandbox repo, and tick a checkbox, because an agent should never open issues on someone else's project by surprise.
Decisions I'd defend
- Recency matters. Each commit-file pair decays with a one-year half-life, so last month's work counts more than work from years ago.
- Mass commits are noise. Merge commits, bots and commits touching more than 40 files are dropped. A repo-wide reformat says little about who understands the code.
- Privacy by default. Author emails are hashed. Only public Git metadata is used.
- Show your work. The UI lists every tool call with its Cypher beside the subgraph it used.
- Same tools, three doors. A built-in agent (any OpenAI-compatible LLM, or an offline rule-based planner with no API key), an MCP server exposing the same graph tools, and a small web UI.
What it can't tell you
- Commit counts are not expertise. A reviewer who never commits is invisible.
- One person with two commit emails shows up twice.
- Scores and thresholds are heuristics, not calibrated probabilities.
- For a module one person owns completely, successor suggestions fall back to weak co-change links.
- I haven't tested it on very large repositories.
Try it
git clone https://github.com/KomalDeep355/HandoffGraph.git
cd HandoffGraph
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
docker compose up -d
.\scripts\run.ps1 ingest
.\scripts\run.ps1 serve
Open http://localhost:8000 and ask: "What happens if the top contributor leaves?"
What's next
Add review and issue data to the graph so reviewers stop being invisible, merge contributor identities, and track how risk changes over time instead of taking one snapshot.
Top comments (0)