handoff: letting parallel Claude Code sessions know why each other changed things

A developer built handoff, an open-source system that lets parallel Claude Code sessions share the reasoning behind their edits by recording prompts, decisions and needs in a FalkorDB graph that every session reads and writes. Claude Code hooks capture each prompt and edit, a small MCP server exposes tools to record decisions, send messages and ask questions, and idle sessions are woken via an asyncRewake hook. In a rehearsal building a small shop app, three sessions made 31 edits across 19 files, recorded 15 decisions with reasons, resolved 3 of 4 cross-role needs and read each other's work 17 times, with the deploy session summarizing changes without being shown a diff.

Demo video: https://youtu.be/16bKhR6Q08c https://youtu.be/16bKhR6Q08c I run Claude Code in several terminals at once: a frontend session, a backend session, a deploy session. They are good at their own work and blind to each other. The backend session can read the frontend's diff, but a diff says what changed, never why : what the person asked, what was decided, what the frontend still needs from the backend. So I ended up as the messenger, copying context between terminals. Put the intent in a graph that every session reads and writes. Not the code, the why : I chose FalkorDB because the questions are about relationships: which request caused this edit, who read whose work, what links the backend's change to the frontend's decision. Claude Code hooks record each prompt and edit as it happens. A small MCP server gives each session tools to record decisions and needs, send messages, and ask questions. When a session submits a prompt it gets, as plain context, what others did and what is waiting for it. An idle session is woken by a message through an asyncRewake hook. Ask a role that has no live session and a stand-in answers from that role's recorded history, citing its sources. All of it runs on your Claude Code login: no API key. On top of the graph: algo.WCC finds files two roles both changed, PageRank finds work other roles lean on, label propagation finds themes in the knowledge graph. Pipeline , Job and DatabaseTable on its own . graph guide tool teaches Claude the graph and FalkorDB 4.22's quirks, and the sessions query it through FalkorDB's read-only MCP server. handoff ask "which needs are still open?" prints the Cypher it wrote. handoff demo opens a tmux grid with three real Claude Code sessions and a live feed. In one rehearsal, building a small shop called ShopLite, the three sessions made 31 edits across 19 files, recorded 15 decisions with reasons, resolved 3 of 4 needs between roles, and read each other's work 17 times. The deploy session summarised what the others had changed and why without being shown a single diff. The coordinator found a need that had sat open for 95 minutes and reminded the backend, which then offered to write the missing tests. Three real Claude Code sessions in a tmux grid, with the live feed in the corner: Mission control handoff dashboard shows the same graph live in a browser: sessions drawn as small Macintosh agents with the messages, reads and needs between them, who learned from whom, the six kinds of memory, a time-aligned log, and the graph itself. A $ field at the bottom of every page lets you message a session or ask the graph in plain words. The orchestration page: a workflow of sessions, with a line for each message, read and need. Who learned what from whose work, with the decision and the reason behind it. The shared graph itself, drawn live from FalkorDB. The log lines events up by time across sessions, so an empty cell means that session did nothing then. And the chat: plain-language questions, with the Cypher Claude wrote kept so you can check the answer. EXISTS {} is unsupported; shortestPath is directed only; algo.betweenness is a . I wrote them down and put them in handoff demo --workspace . would have deleted a whole project. Another found that two projects on one machine shared a graph and could read each other's prompts. uv tool install "handoff knowledge @ git+https://github.com/adityailab/graph-agent" cd your-project && handoff init handoff demo Needs Docker, Claude Code and uv. FalkorDB runs in a container bound to localhost, and prompts pass through a redactor before they are stored. There are 655 tests, and the whole design, plan and decision log are in the repo.