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.
