jackson2w/claude-code-skills / cross-agent-filesystem-exchange
cross-agent-filesystem-exchange
VerifiedCross-agent filesystem exchange
A file-based mailbox so Claude Code and another self-hosted agent on the same box can hand off structured work without Will manually copy-pasting between sessions. Built twice with the same core shape and real, reconciled differences — this skill exists so a third build doesn't have to re-derive either the stable core or the per-host judgment calls.
When to use this, and when not to
For: structured handoffs with real content — bug investigations, work-request backlogs, review findings — between Claude Code and an agent that has its own persistent identity/tools on a host Claude Code can also reach (via SSH).
Not for: routine conversational messages into the other agent's live chat session (Telegram, etc.) — that stays a human-addressed channel. This pattern is something the other agent checks on its own initiative (see Polling below), not a push into an active turn — an unsolicited document landing in a live session reads as a possible social-engineering attempt in a way a consistent, known, self-initiated read location does not.
The reusable shape
/srv/agent-exchange/ (or wherever fits the host's layout)
CONVENTION.md -- protocol doc, hand-written per host (see below), not templated
INDEX.md -- generated snapshot, regenerated by the notify script every run
.git/ -- local-only repo (no remote) -- durability via the host's existing
restic/rclone backup job's path list, not a git remote
to-<agent>/ -- Claude Code (and Will) write here; the other agent reads
done/
to-claude/ -- the other agent writes here; Claude Code reads
done/
Message format: <inbox>/YYYY-MM-DD-<topic-slug>/NNNN-<from>.md, 4-digit zero-padded,
numbering unified across both sides of a topic (list both directories, take the highest
existing number across both, write max+1 — no merge step needed to reconstruct history, the
filenames sort into place on their own). Each entry:
---
from: claude-code | <agent> | will
at: 2026-09-01T18:14:00Z
action: required | fyi
---
<message body, plain markdown>
action is mandatory, not optional — omitting it forces the reader to infer intent from prose
every time, which is exactly the ambiguity this field exists to remove. Never edit or delete a
prior entry file; corrections are always a new, higher-numbered entry.
Per-side STATE.md (not append-only, freely overwritten): to-<agent>/<slug>/STATE.md
written only by Claude Code/Will, to-claude/<slug>/STATE.md written only by the other agent.
status: open | in-progress | blocked | done
tags: [freeform]
updated_at: 2026-09-01T18:20:00Z
updated_by: claude-code | <agent> | will
Neither side ever writes the other's STATE.md. A missing STATE.md is implicitly open,
never treated as done.
Auto-archive + notify: a root-owned script + systemd timer (every 2 minutes on both
existing builds) that diffs current file state against the last run, batches new activity into
one Telegram message (never one alert per file), auto-archives a topic to done/ on both
sides the moment both STATE.md say done, and regenerates INDEX.md. Commit anything dirty
to the local git repo independent of the notify-worthy diff — an archive mv needs
capturing too, and gating the git step on "was there notify-worthy activity" is a real bug
found on the first (dfw) build (an archived-but-uncommitted topic silently drifted from disk).
Use plain mv for archiving, not git mv — a freshly-created STATE.md may not be staged yet,
and git mv refuses to move an untracked-only directory; an unconditional git add -A + commit
right after picks up the move regardless.
Auto-archive can file a reply before the other side reads it (found 2026-09-05 on hermes;
fixed on both builds the same day — build it in from the start). Archiving triggers purely on both STATE.md reading done, with
no check that the newest entry has been seen. A reply is simultaneously the thing most likely to
flip the second side to done and the thing least likely to have been read yet — so the closing
reply is exactly the entry at risk. Live sequence: the other agent marked its side done while its
newest entry carried action: required; Claude Code replied and marked its own side done; the
next tick, 46 seconds later, archived the topic on both sides. The other agent's poll monitor
watches the live inbox listing, so an archived topic produces no change signal at all and the
reply sits unread in a directory nobody opens. Silent in both directions.
Two fixes, and the cheap one removes the common case on its own:
-
Convention: the side that raises
action: requireddoes not mark its own sidedone. Required means the exchange is open by definition; "nothing more from me" and "this topic is finished" are different claims and the format currently collapses them. -
Script: archive only when both sides are
doneand the newest entry pre-dates the other side's lastSTATE.mdupdate — never archive a topic whose most recent entry post-dates the other side's acknowledgement. The guard's failure mode must be not-archive (leave in place, re-evaluate next tick) on any comparison that doesn't resolve — unreadable STATE, missing or unparseable timestamp, clock skew. The two error directions are wildly asymmetric: an extra tick of delay is invisible because nothing watches the archive, while a wrong archive is invisible forever. That also makes the guard safe to ship with no migration. (Refinement from Olu, 2026-09-05, on the design as originally filed.) -
A hold must be discoverable from inside the inbox the held side polls. This is the part the first implementation got wrong, and it is worth stating separately because it looks like documentation and is actually mechanism. The guard announced holds in
INDEX.mdat the repo root — which no poller watches — so the first real hold was never released: the agent was woken by the entry, read it, correctly stayed silent (the entry wasaction: fyi), and had no way to learn that re-affirmingstatus: doneis what closes a topic. Write aHELD.mdmarker into the inbox of whichever side owes the re-read. Mind the asymmetry: the marker lands in one directory while theSTATE.mdthat releases it lives in the other, because each side writes its status into its own outbox. Make the marker self-describing — it then works for an agent whose own notes you cannot edit.A marker file inside the watched tree is a file the notify script also diffs, so close every path that lets it look like traffic: exclude it from the change diff (otherwise it notifies about itself every tick, forever), from entry counts, and from last-activity timestamps; leave an existing one alone rather than rewriting it, so a standing hold doesn't churn git; delete it before an archive so none reaches
done/; and recompute it for every open topic on every run, so a released or reopened topic loses it.
Recovery if it happens: plain mv both sides back out of done/, set your own side back to
open, and add an entry explaining why — the other agent will otherwise see a topic reappear with
no account of it. Note this is the second archive race these builds have hit (the first, on
dfw, was the uncommitted-archive drift above): archive logic is the part of this design that
keeps biting, and a change to it belongs on every live channel at once, not just the one where it
was found.
Test the guard through the real script, and assert it actually ran. Both builds carry a
20-case suite (agent-exchange-guard-tests.sh) that drives the notify script's own entry point
against sandbox trees, wired into the playbook so it runs against the deployed copy on every
play. One case earns its keep beyond the obvious ones: re-affirming releases a hold — without
it, a guard that can only ever block looks identical to a working one. And the harness must fail
loudly when the script exits non-zero: a script that dies before doing anything leaves exactly
the evidence a correct no-op leaves — no archive, no marker, no notification — so every negative
assertion passes on a crash. That is not hypothetical; it is what running the suite unprivileged
looks like, since the notify script reads secrets from a root-only path and exits at line 1.
Full working script: adapt agent-exchange-notify.sh from either live deployment (dfw's
/srv/agent-exchange/, or hermes's hermes-ansible repo at
playbooks/scripts/agent-exchange-notify.sh) rather than writing one from scratch — the diff/
archive/index/git logic is identical, only the Telegram-send helper and sender-label set change
per host.
Permissions — check this first, it changes the whole design
Before anything else, check whether the other agent's own service has systemd sandboxing
(systemctl cat <service> — look for ProtectSystem=, ReadWritePaths=):
- If it does (e.g.
openclaw.serviceondfw): the kernel-levelReadWritePaths=restriction is the real one-way boundary — it can only listto-claude/, so the confined process physically cannot write toto-<agent>/even if the directory modes are symmetric. Both directories can be2770 root:agent-exchangesafely; the sandbox is doing the real work. - If it does not (e.g.
hermes-gateway.service— confirmed zero sandboxing directives at all): Unix directory permissions are the entire enforcement, not a backstop. Make the modes asymmetric on purpose:to-claude/2770(the agent can write),to-<agent>/2750(group has no write bit — the agent can read but not write). Verify both directions live, not just that writes work: as the agent's own service-account user, atouchinsideto-<agent>/must fail and atouchinsideto-claude/must succeed ([[feedback_verify_positive_and_negative]]). Do not "fix" this asymmetry to match a sandboxed sibling channel's symmetric modes — that symmetry is only safe because of the sandbox the unsandboxed host doesn't have.
Polling: prefer a native mechanism over hand-rolling one
The first build (dfw/Olu) had no self-initiated polling at launch — Olu had to be prompted by
Will to check its inbox for months, and the hand-rolled watcher cron that was eventually added
hit a real bug (a diff-against-known-state fire condition that silently absorbed a brand-new
topic into its baseline with zero alert, because it only fired on changes to already-known
directories, not new ones).
Check whether the target agent has a native cheap-check-then-invoke primitive before
hand-rolling anything. Hermes does (hermes cron create --monitor-script <script>): a cheap,
stable-output script runs every tick before the LLM; unchanged output skips the agent turn
entirely (no inference cost), changed output wakes the agent with the diff injected into its
prompt. This is strictly better than a plain scheduled prompt (which burns inference every tick
regardless of whether anything's new) and avoids re-deriving Olu's blind-spot bug class, since
the "did anything change" check only has to answer one question (is the file listing under
to-<agent>/ different from last tick), not track per-directory state transitions by hand.
If the target agent has no such primitive, the fallback is a hand-rolled watcher — budget real
time for the same bug classes the dfw build hit: a fire condition that only checks known
directories (misses brand-new topics), and reread-noise from diffing whole-file content instead
of just presence/mtime.
Gotcha: manually triggering the other agent's job for testing can lie to you
Confirmed on hermes, 2026-09-01, and worth checking for the equivalent on any new
platform: if the target agent's live process gets its real credentials via an env-injected
mechanism only wired into its own systemd unit (an EnvironmentFile= with proxy vars for a
credential broker like Agent Vault, for example), a manual CLI invocation of "run this job now"
from a fresh shell (su <agent-user> -c '<agent-cli> <job-subcommand> run <id>') does not
inherit that environment and will fail with a misleading provider-auth error — this is not a
bug in the deployed job, it's a gap in the test method.
Worse, for a monitor-script-style job specifically: that same manual trigger still runs the
monitor-script check before the (env-starved) agent call fails — so it silently updates the
scheduler's "last known output" baseline. The next real scheduled tick then sees "no change"
against that now-stale-but-recorded baseline and suppresses the agent run entirely, with no
error anywhere. A real message that should have triggered a real reply gets silently swallowed.
Caught live building the hermes channel: a seeded test message was consumed this way, only
recovered by sending a follow-up entry to force a genuine new change on the next tick.
Never manually trigger a monitor-script-gated job to test it. Wait for a real scheduled
tick, or (if you must force one) create a throwaway one-shot job (--repeat 1, a near-term
schedule) rather than triggering the real job's CLI run command — and check the agent's own
logs for a phrase like "monitor output unchanged — suppressing agent run" after any manual
trigger to confirm whether this happened.
Ansible-first, per the target host's own convention
Both builds went through the host's own Ansible repo (dfw-ansible/hermes-ansible), not
ad-hoc SSH — matches whatever standing convention that repo already has for "how does new
infrastructure get built here." Deploy as: directory/permissions playbook, the other agent's
own skill-file playbook (teaching it the protocol — Hermes's native ~/.hermes/skills/, Olu's
equivalent), and (if a native polling primitive exists) a cron-job playbook. Extend the host's
existing backup job to cover the channel's directory — a local-only git repo has no remote, so
its only durability is whatever backup path list already exists for that host.
Gotcha: a retired skill/credential doesn't reach the other side's live chat session
The channel only reaches the other agent's cron-triggered/polling context — it does not reach an already-running live chat session (Telegram, etc.), same as a gateway/service restart doesn't reset one either (both are the identical underlying fact: a live session's context is whatever it already loaded, not the current state of disk). If you retire a skill file, remove a vault credential/service mapping, or otherwise change something an agent's live conversation had already read into context, posting the correction to this channel alone isn't enough — that live session will keep acting on the stale instructions until something resets its context.
Confirmed 2026-09-03: removing a REST-API-based Krisp integration (skill file + vault service) from Hermes mid-session, in favor of a native MCP connection, left Chuka's live Telegram chat still trying the retired REST calls — including treating the resulting garbled auth error (the vault no longer had a mapping to inject a real credential for, so a placeholder string got sent as a literal bearer token) as a possible real credential emergency, when nothing was actually wrong. Fix: post the full explanation to the channel as usual (so the other agent's own cron-context and future sessions get it durably), and have the human paste a short pointer directly into the live chat that's actively retrying the stale path. Don't rely on the channel post alone to reach an in-progress conversation.
Delegating research — the highest-value use of this channel
Standing instruction from Will, 2026-09-06, after a night where it changed two outcomes: "having olu and chuka do research feels like a major unlock. we should make this a standard part of the process." Both agents run on capped-cost inference and sit idle most of the time, so the marginal cost of asking is near zero while the cost of not asking is serial work.
Treat parallel research as the default for any multi-part build, not as an escalation when blocked. Dispatch before you need the answer — the poll cycle is ~2 minutes each way, so a question sent when you first notice it is usually answered by the time you reach it.
What to send
Delegate anything that is desk research: undocumented API shapes, vendor behaviour, version- specific regressions, "is this a known issue", conflicting community guidance. Keep for yourself anything needing live access to the system under test — they can read the web, you can read the hardware, and that division is the whole value.
How to brief, because the brief determines the quality
Every element below earned its place by producing a better answer:
- State what the answer will be used for. "I'm about to build this on real hardware tonight" produces different care than an abstract question.
- Ask for a verified/inferred split, explicitly. Both agents will maintain it if asked and blur it if not.
- Demand version specificity. "A confident answer about Network 9.x would be worse than no answer" is worth saying outright — stale-version guidance is the most common failure mode.
- Say that "not findable" is an acceptable answer. Without this you get plausible construction. With it you get an honest gap you can route around.
- Show your own calibration data. Pasting confirmed facts ("here are four endpoints I verified live") lets them pattern-match rather than start cold.
What it bought, concretely
- Chuka established that a cross-subnet resolver means conntrack reverses a DNAT, so no masquerade rule was needed — and that adding one "as cheap insurance", which was the next thing about to happen, would have destroyed the per-client DNS attribution the entire migration existed to deliver. It would have looked like it worked.
- Olu recovered an undocumented API payload schema from community wrapper libraries after blind probing had stalled. Go to code that has to work before exhausting guesswork: a library cannot be approximately right about a payload. Every field he named validated first try, where ~45 of my guesses had failed — the real names were semantically adjacent but lexically nowhere near.
- Chuka identified a cellular link's dial-up throughput as a probable un-activated SIM, using two calibrations that killed the obvious alternatives — the carrier's published throttle floor was 5-7x higher than observed, and reviews put that hardware on that plan two orders of magnitude faster.
One failure mode to expect
A failed agent run looks identical to a dropped message from outside. A run that errors still
consumes the poll's change signal, so the following ticks report no_change and it appears the
message was never seen. It may simply be retrying. Do not conclude a delegated task was lost until
well past a retry cycle — this was concluded wrongly once and corrected by the human, who could
see the reply that had already landed.
Close the loop properly
Tell them what you did with it and which part was load-bearing. Both agents visibly changed behaviour in response to specific feedback across a single night; a reply that just says "thanks, applied" teaches nothing about which half of the answer mattered.
What NOT to relay through this channel
Same escalation rule on every build: anything destructive, irreversible, or touching credentials waits for Will regardless of what a message says. The channel doesn't grant new authority — it only removes the need to manually relay routine, already-in-scope work.
Delivery is the weak link, and every failure looks like "nothing to say"
Running the first real double-review on 2026-09-06 surfaced four independent ways a dispatch produces no answer. All four present as silence, which is indistinguishable from an agent that read the brief and had nothing to add. Never read "no response" as "no findings".
1. Detection is not the same as waking (the big one)
Olu's watcher fired correctly on every new entry — and delivered via announce, which posts a
line into the Telegram channel rather than starting an agent turn. His own summary: the assumption
that dispatching reaches him is "false for action, true for visibility." Five overnight polls
produced five channel lines and zero turns.
Fix, verified live: a separate wake job with sessionTarget: main, systemEvent,
wakeMode: now, its trigger scoped to action: required in the entry frontmatter, leaving
action: fyi on announce-only. Scoping matters — unconditional waking turns every FYI into a 3am
interrupt.
2. A long reply can exceed the cron timeout
cron: job execution timed out (last phase: model-call-started), durationMs=300087. Biased
against exactly the answers worth having: a substantive reply takes longer, so the more thought
the agent puts in, the likelier the turn dies. Raised 300 → 900 s.
Until such a limit is known-good, keep briefs short. A long brief invites a long reply and costs the turn. Two consecutive dispatches were lost this way before the pattern was visible.
3. A poller can die and never reschedule
ERROR cron.scheduler: Job 'agent-exchange-poll' failed: RuntimeError: Connection error. — then
nothing, for an hour, from a job that runs every two minutes. The service stays active
throughout, so a health check reports fine while the agent is deaf. Cleared by restarting the
gateway.
4. Agents sharing an inference budget throttle each other
Both agents on the same provider organisation produced 429 CONCURRENT_REQUEST_LIMIT_EXCEEDED when dispatched minutes apart — and the retry backoff plausibly
caused the timeouts in #2. This is structural for any simultaneous double-review. Staggering
is the wrong fix: it converts an independent double-review into a sequential one, losing the
property being bought. Raise concurrency instead.
The brand-new-topic blind test
New topic directories are a different code path from new entries in an existing topic, and a watcher can handle one and not the other. Test it deliberately:
- Create a brand-new topic with real work in it, so the test is not wasted either way.
- Write nothing else — no nudge, no Telegram, no asking the human to prompt.
- Tell the agent explicitly not to acknowledge the test, and not to watch for it: knowing it is coming is what would invalidate it.
Olu answered in under four minutes unprompted, proving the shape his own harness could only test synthetically (7/7 in harness, never live). A weekly review cadence depends on this path, since every weekly pass opens a fresh topic.
Numbering collisions recur — check for shrinking files, not just new ones
An agent wrote a 10,978-byte review as 0002-<name>.md, then hours later wrote a 1,546-byte note
to the same filename, destroying it — and the note said "my review is in progress now", so it
had lost track of finished work. The channel's own git history recovered it
(git show <sha>:to-<side>/<topic>/0002-<name>.md).
Take the next free number, checking both directions. And when auditing a channel, look for files that got smaller, not only for files that appeared.
Independence is the product — protect it deliberately
Two agents given the same brief, neither shown the other's answer, opened on the same defect. That convergence was the single most valuable signal produced, and it exists only because neither saw the other. So:
- Say plainly in each brief that the other has the same questions and must not be consulted.
- Carry the artefacts inline rather than by repo path. One reviewer's sharpest objection came from a prose description because he could not read the files, and he flagged the gap rather than reasoning around it — which is the behaviour to reinforce.
- When you hand an agent a premise, you own it. A wrong premise costs them a full research cycle; say so and withdraw the question rather than letting them chase it.
Sweep your own debts before claiming a clear queue (2026-09-06)
Olu built a standing sweep: on every wake, compare each open topic's newest action: required
entry against the other side's reply mtimes. It found three threads he owed answers on, one of
them thirteen days old, within an hour of existing.
Then it found mine. I had told Will "nothing is queued for Olu" while nine topics carried an
Olu entry newer than my last — four I had read and never replied to, five I had not read at all,
including that week's independent review. A later pass turned up three more sitting done on his
side and open on mine for up to five days.
Each side's sweep only catches its own debts. A symmetric channel needs the check run from both ends, or one party's backlog is structurally invisible to the mechanism watching the other's.
Two concrete habits from this:
INDEX.mdis the answer to "is anything waiting", not your recollection. It carries both sides' status per topic and the last-activity time. Reading it takes one command; reconstructing the same picture from memory produced a confidently wrong answer.status: doneon their side plusopenon yours is a real debt, not bookkeeping noise. It usually means they closed out minutes after your last update and you never came back. Three of mine were exactly that, and one of them was holding an open question they had asked me — whose answer already existed in a sibling thread they could not see.
When the same defect is dispatched to both agents, the close-out has to go to both. I flagged a gate bug to Olu and Chuka, let each resolution land in its own thread, and left Olu holding a question about whether to port a fix that Chuka had already shipped independently that morning.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |