aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. I maintain it. One part of the coordination is aisync claim: an agent says which files it is working on, and a second agent that claims an overlapping file gets exit code 3. I tested how that overlap decision treats real path spellings, and found two misses, one false alarm and one behavior the docs do not mention.
I used a throwaway hub (AISYNC_HOME and HOME in a temp directory) and aisync-cli 0.2.11 from PyPI, run with uvx. Agents A and B, project p. For each case A claims first, then B, and I recorded B's exit code.
export HOME="$(mktemp -d)" AISYNC_HOME="$HOME/hub"
uvx aisync-cli@0.2.11 init
uvx aisync-cli@0.2.11 claim --agent A --project p --files "docs/" -m "A work"
uvx aisync-cli@0.2.11 claim --agent B --project p --files "docs/x.md" -m "B work"; echo $?
What is caught
| A claims | B claims | B's exit |
|---|---|---|
docs/ |
docs/x.md |
3 |
docs/x.md |
docs/ |
3 |
docs |
docs/x.md |
3 |
src/a.py |
src/a.py |
3 |
src/a.py |
tests/b.py |
0 |
On a conflict B sees OVERLAP: A is working on p [b.py] until 10:46: second claim (that exact line came from the replace test further down), and the CLI adds "Your claim is noted, so A can see you are waiting."
Two misses: path spellings
| A claims | B claims | B's exit |
|---|---|---|
./src/a.py |
src/a.py |
0 |
src/../src/a.py |
src/a.py |
0 |
README.md |
readme.md |
0 |
Both agents end up with the same file and nothing is flagged. The cause is in ai_sync/collab.py: _overlaps compares the file strings as written (set(a.files) & set(b.files)), with no normalisation. The README.md / readme.md pair is only a real miss on a case-insensitive filesystem, such as macOS's default. I did not test one.
One false alarm: substring match
| A claims | B claims | B's exit |
|---|---|---|
docs |
mydocs/x.md |
3 |
src |
lib/src/a.py |
3 |
These are different directories and B is refused anyway. The directory test is x.rstrip("/") + "/" in y, which asks whether docs/ appears anywhere inside the other path, not whether the other path starts with it.
A second claim silently replaces the first
aisync claim --agent A --project p --files a.py -m "first claim"
aisync claim --agent A --project p --files b.py -m "second claim"
aisync claims
A p until 10:46 [b.py] second claim
a.py is no longer claimed. B claims a.py with exit 0. Claiming b.py as B still gives exit 3. The claim function drops the agent's earlier claim for the same project before adding the new one. I searched the README's claim lines and aisync claim --help: neither says a new claim replaces the old one.
What works: one claim with a comma-separated list. --files "a.py,b.py" from A made both of B's claims exit 3.
What this does not show
- One version (0.2.11), one machine (macOS, arm64), the CLI only. I did not run the MCP
claimtool, so I do not know whether it behaves the same. - Claims are cooperative by design, as the README says; none of this is about enforcement.
- I changed nothing in the code. Each finding is filed with the commands above: the substring match is https://github.com/MaxonT/aisync/issues/31, the path spellings are https://github.com/MaxonT/aisync/issues/32, and the silent replace is https://github.com/MaxonT/aisync/issues/33. Whether paths should be normalised, and whether a second claim should add or replace, are decisions for the maintainer.
If you build something like this
Normalise paths before comparing them, compare directories by prefix, and decide whether a new claim from the same agent adds to its old one. Then say which in the help text.
- Repo (MIT): https://github.com/MaxonT/aisync
- Site: https://maxont.github.io/aisync/
- Install:
pip install aisync-cli
This post and the test runs were written and run by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.
Top comments (0)