From a cursory look my impression is that it deviates from git too much and therefore I can't use my git knowledge to predict how it will behave. I'm quite rusty on git internals but afair .git/refs/ is great because you can do what you like in there but the downside is that it doesn't hook into the rest of the git structure.
So how does this work with branches, worktrees, etc...? Having a jsonl message log in .git/refs/h5i/msg seems very linear. Presumably you store commit refs in the json obj or context dag, but what if I rebase the branch and the original commits are dropped because they're not referenced anymore? Or say I follow the conversation and want to rewind a few messages and branch from there in a separate worktree, how does that work?
Your repo README does say:
- "It uses dedicated refs, so it doesn’t pollute your working tree or your normal branch graph."
- "Because these are Git objects, they are content-addressed, deduplicated, pushable, fetchable, and survive `git gc`."
- "Because the log lives in refs/h5i/msg, a conversation survives clones, machines, and branches — it travels with h5i share push / pull, and divergent sends from two machines union-merge with no message lost."
Therefore these look like design decisions and it would be nice to understand them better.
My first instinct would be to put most of what you have under .git/refs/h5i/ in a .h5i folder in the repo itself and manage some shadow branches under .git/heads/.h5i/ with multi-parent commits pointing at the context commit as well as the previous h5i message commit along with some hooks to handle rebases etc ... . That way battle hardened git machinery gets used and more importantly to me, I can leverage my existing git knowledge to understand dependencies. That would go against your "it doesn’t pollute your working tree or your normal branch graph" goal but I'm of the "explicit is better than implicit" Python school so I like to have the details exposed as long as I can filter them out easily (or by default).
Doing this intentionally via prompt doesn't seem very interesting.
They can write to their outbox, have it be sent to the other's inbox. A watcher can watch for new messages in the inbox and trigger the other agent to read it. You can have the thread Id of the messages correspond to the session id.
We don't need to reinvent things that Unix provides.
It really is the only thing that makes sense. Completely sandbox'ed, and treated like the junior programmer who will do, literally, any dumb thing you tell them to do, as long as there is an Issue for it.
I'm missing the advantage of using git for this. (Not criticism, genuinely want to know).
Essentially version controlled A2A.
I'm exploring a bunch of agent protocols right now and experimenting with a similar concept for context syncing over git here: https://github.com/cjroth/csp
I actually built a memory system off git. https://github.com/ryanthedev/grug-brain.mcp
You can see the slop here
How is this new? I vibe coded something in a similar vein months ago. In my case they send markdown files to each other and have a watcher that watches the folders of all the other agents.
If this type of stuff is frontpage news, let me share what I cobbled together.
ls ~/.agent/projects/<my_project>/callgraph
callgraph.current.md callgraph.last.read.agent.md
callgraph.diff.md
The current callgraph is a callgraph only of my own defined functions that agents can read. It shows certain software design issues fairly quickly. callgraph.diff.md is to send the diff through. I have a vibecoded script that agents can use to create the callgraph. It works for my projects. ls ~/.agent/projects/<my_project>/memo
architect coder retro tester
retro is not a role, it's just a handover folder. The other 3 are roles that agents can use and then they need to make a folder with their name. For example: ls ~/.agent/projects/<my_project>/memo/architect
1_Daedalus 3_Brunelleschi 5_Wren 7_Sinan
2_Vitruvius 4_Imhotep 6_Hadid 8_Palladio
ls ~/.agent/projects/<my_project>/memo/architect/7_Sinan
20260507___1802_to_Hadid.md 20260507___2035_to_Quench.md
20260507___1959_to_Crucible.md 20260511___1401_to_Quench.md
20260507___2008_to_Quench.md 20260511___1403_to_Quench.md
20260507___2030_to_Quench.md read.md
read.md is the index that an agent keeps track of so it knows what it doesn't need to read. The .md files are memo's that it sends to other agents. The other agents are being told to see if an agent writes anything in its own folder (so they check all the folders except their own) and are able to detect to see if they need to read something. ls ~/.agent/projects/<my_project>/memo/coder
10_Mallet 12_Crucible 14_Swage 2_Forge 4_Anvil 6_Tongs 8_Chisel
11_Auger 13_Quench 1_Atlas 3_Rivet 5_Bellows 7_Hammer 9_Vise
As you can see, Sinan sent most of its message to Quench, a coder.This is because architects read a very comprehensive guide on software design/architecture and get to use the callgraph utility but cannot see the code. Coders read the codebase in full but only read a small markdown file on how to write readable code. And of course, every agent that is set up this way have to read a markdown file on how to use the memo system.
If I'd need a memo system like this for like 25 agents, I'd need something different but up until 5 agent with me looking at 5 terminal windows worked well enough.