Why it was needed
Every rule here started as a failure. These four shaped the system most.
- Aug 2026Three days of work on one disk
A desktop was found holding eight unpushed commits, including a full incident write-up. No other machine had any of it.
- Aug 2026The same bug, reported three times
An agent copied a panel feature without the code it relied on. The button did nothing, Esc did not close it, a control was missing. Each was a separate report with one root cause.
- Oct 2026Reading the wrong rules
An agent opened from a synced folder read an outdated copy of the instructions and did not know its role.
- Oct 2026Two claims, both "successful"
In a test, two lock-tool runs on one machine overwrote each other's claim in 3 of 5 tries, and both reported success.
One repository, layered rules
All code, documentation and agent memory live in one private repository. It is the only way machines hand work to each other.
CLAUDE.mdShared floor. Multi-machine workflow, commits and pushes, credentials, how to build a web page. Every agent on every project follows it.
<project>/CLAUDE.mdProject entry document. Only what is specific to that project: how to deploy, where it lives, its traps. It may be stricter than the floor, never looser.
<side>/WORKFLOW.mdSide branches. Optional work keeps its own plan and log, and agents skip it unless the task names it, so unrelated sessions do not spend context on it.
If two layers disagree, the agent follows the stricter one, and if it is still unsure, it asks me. An AGENTS.md mirrors the rules for non-Claude tools. Short pointer files sit in the places agents tend to wander into, such as the synced folder and old course directories, and send them back to the real workspace.
Read only what changed
Each machine stores a marker: the last commit it has read for each project. A new session lists the commits since then that touched the files it cares about, and reads only those diffs.
A session starting on each machine
illustrative historygit fetch -q "$GH" main
SEEN=$(cat .git/ai-seen-$P 2>/dev/null) # this machine's marker, never committed
W=($P CLAUDE.md LOG.md SKILLS.md SECRETS.md) # files that matter to this project
git log --oneline ${SEEN:+$SEEN..}FETCH_HEAD -- "${W[@]}"
git pull -q --ff-only "$GH" main
# empty list: read nothing. otherwise: git diff $SEEN..HEAD -- "${W[@]}", then move the marker
An empty list means nothing changed, so the agent rereads nothing and starts work. That one rule cut most of the reading at the start of each session. The logs are capped at 20 entries. Older ones move to an archive no agent reads by default, which took the main log from about 44,000 tokens to 19,000.
Hand off through a log and a plan
The log says what happened. The plan says what is still open. An agent that stops halfway leaves both behind.
Log entry
newest first · at most 5 lines## v2026.11.05-1 · Main Mac · Claude Opus 5.5 - What changed and why (the conclusion, not the process) - Files touched / what was deployed / what was NOT verified
Plan item
self-contained- [ ] Action, in one line
- what was already checked, the options
on the table if a decision is pending
- exact commands or UI path, IDs
- do NOT touch: …
- what to log when doneAnything an agent thought of but did not do goes into the plan at once: proposals waiting for my decision, problems it noticed and left alone, steps only I can do on another machine. Nothing is left as a "by the way" in a chat that the next agent will never see. When the newest log entry contradicts what I just asked for, the agent checks with me before acting.
Claim before you touch
For the websites, a small tool called zl keeps a registry in the same repository: who holds which domain, hosting project or server slot, from which machine, until when.
Two agents, one domain
simulated · same messages and exit codes as the tool$ # press a button
Every write is fetch, change, commit, push. A rejected push means another machine wrote first, so the tool rereads and tries again. Claims expire after a few hours. A claim held by someone else returns exit code 2, and the rule is to stop and tell me, never to pick a different name to get around it. Runs on the same machine share one file lock, which fixed the race in the test above.
Commits per month
work vs. lock-tool bookkeeping · Nov to the 20thData table
Rules that came from corrections
When I had to correct an agent twice for the same kind of thing, the fix went into the rules, so the next agent starts with it.
- Push every change, immediately
Not at the end of the session and not batched. Each change gets its own commit and push, and a failed push has to be reported. Never force-push; a conflict in someone else's folder means stop and ask.
- A behaviour gets one implementation
Before writing a modal, toast or formatter, search for the existing one and import it. Moving a feature means moving what it depends on. A second copy is never correct.
- Unverified means not done
An error stops the work until it is understood. A deployment counts only after it is checked live, and the report lists what was not tested.
- A permission error means stop
If a scoped credential lacks a permission, report what is missing. Do not switch to a stronger credential to get past it.
- Secrets are read, never copied
Credentials are registered in one index and read from their files at the moment of use. They never go into code, logs or replies.
- One name per machine
"The old MacBook" means exactly one computer, the home gateway. Agents mixing up two MacBooks caused real mistakes, so the name is fixed.
What it does not solve
The system makes agents dependable colleagues. It does not make them autonomous.
Anything risky still waits for me: deleting, taking things offline, changing live configuration, spending money. Rules cost tokens every session, so they have to stay short, and pruning them is ongoing work. Conflicts between machines are rare because of claims and constant pushing, but when they happen I resolve them. The same setup built the projects next to this one, including the home network.