open/repo-mailbox
1
0
Fork 0
Code Issues Releases 2 Activity

feat(hook): let a non-git surface declare its identity via CLAUDE_COORD_REPO

Browse source 
0.6.0 removed the working-directory fallback, which was right, but it left
every non-git working surface with nothing to derive from. The read path
declines silently by design - the hook must never fail a session - so such a
surface simply stops seeing its inbox: no error, no exit code, nothing. That is
the same loss-looks-like-normal shape 0.6.0 set out to remove, reintroduced one
layer up.

The hook now forwards CLAUDE_COORD_REPO verbatim as --repo. This is not the
fallback returning, and the distinction is the whole point: the fallback GUESSED
a name from wherever the session happened to stand, while a declaration is
written down in that directory's settings, readable back, and deletable.
Identity stays a choice someone made.

Forwarding as --repo rather than reimplementing anything means it inherits every
engine rule, including that an explicit override never claims <repo>/.origin -
otherwise a surface borrowing a name would steal the claim from the checkout
that owns it. Both halves are pinned by tests, and the shared test helper now
deletes CLAUDE_COORD_REPO unless a test asks for it, so a value set globally
later cannot silently satisfy the tests that prove the hook resolves nothing on
its own.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U6EixQo6hpoRCVtiAXdnFs
This commit is contained in:
Kjell Tore Guttormsen 2026-07-27 08:56:31 +02:00
commit 28e7cb42cd
7 changed files with 91 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -8,7 +8,7 @@
*AI-generated: all code produced by Claude Code through dialog-driven development.*
![Version](https://img.shields.io/badge/version-0.6.0-blue)
![Version](https://img.shields.io/badge/version-0.7.0-blue)
![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple)
![Hooks](https://img.shields.io/badge/hooks-1-green)
![Skills](https://img.shields.io/badge/skills-1-orange)
@ -36,6 +36,12 @@ Mailbox layout (default `~/.claude/coord/`, override with `CLAUDE_COORD_DIR`):
Repo identity is the basename of the git toplevel, or an explicit `--from`/`--repo`. There is no third source: a directory that is not a git repo has no identity, so the write paths refuse and the read path stays silent. (The old fallback to the working-directory name was removed in 0.6.0: on a global surface like `~/repos` it silently invented the identity `repos` for a directory that is no repo at all, and signed real mail with it.) There is no registration — a repo joins the moment something is sent to it, or when it first reads a broadcast.
**Declaring an identity for a non-git surface.** A working directory that is not a git repository (`~/repos`, `$HOME`) has nothing to derive from, so the read path declines silently and that surface never sees its inbox — loss wearing the shape of normal. Set `CLAUDE_COORD_REPO` in that directory's `.claude/settings.json` to say which mailbox it owns:
{ "env": { "CLAUDE_COORD_REPO": "repos" } }
The hook forwards it verbatim as `--repo`, so it inherits every engine rule — including that an explicit override never claims `.origin`. This is a *declaration*, not the old working-directory fallback: the fallback guessed a name from wherever you happened to stand, while this is a value someone wrote down, can read back, and can delete.
Because identity is a *basename*, two checkouts with the same directory name share one mailbox. The first git-derived read records the claiming path in `<repo>/.origin`, and a read from a different path is warned about in the injection. It is a warning rather than a refusal: the same repo moved or re-cloned is the ordinary case. Names beginning with `_` are reserved for engine internals (`_broadcast`) and are refused as repo identities everywhere.
Message format (filename `<UTC-timestamp>-<uniq>-from-<sender>.md`):