diff --git a/crates/git-credential-nostr/README.md b/crates/git-credential-nostr/README.md
index 827f8d55a3..9c545b7851 100644
--- a/crates/git-credential-nostr/README.md
+++ b/crates/git-credential-nostr/README.md
@@ -28,6 +28,39 @@ git config --global nostr.keyfile ~/.nostr/key
 
 That's it. Use git normally — `git clone`, `git push`, `git fetch`.
 
+### macOS: scope the helper to your relay
+
+On macOS, Xcode's bundled gitconfig registers `osxkeychain` as a credential
+helper for every repository:
+
+```
+$ git config --show-origin --get-all credential.helper
+file:/Applications/Xcode.app/Contents/Developer/usr/share/git-core/gitconfig   osxkeychain
+```
+
+`git config --global credential.helper nostr` **appends** to that chain rather
+than replacing it. Both helpers run, and after each successful operation git
+asks every helper in the chain to store the credential — osxkeychain cannot
+store the Nostr credential shape and prints:
+
+```
+failed to store: -1
+```
+
+Operations still succeed; the error is pure noise. To silence it — and to keep
+the helper from ever running for github.com or other hosts — register the
+helper scoped to your relay URL instead of globally (the same idiom GitHub's
+`gh` CLI uses):
+
+```bash
+git config --global --add credential.https://relay.example.com.helper ""     # reset the chain for this URL
+git config --global --add credential.https://relay.example.com.helper nostr
+git config --global credential.useHttpPath true
+```
+
+The empty first entry resets the helper chain for that URL, so only `nostr`
+runs against your relay and osxkeychain keeps handling everything else.
+
 ## CI / CD
 
 Set `$NOSTR_PRIVATE_KEY` instead of a key file. The env var takes precedence
@@ -66,4 +99,5 @@ git ──stdin──▶ git-credential-nostr ──stdout──▶ git
 | `method hint` | Server's `WWW-Authenticate` header is missing `method="..."` | Upgrade the Buzz server |
 | `useHttpPath` | `credential.useHttpPath` is not set | `git config --global credential.useHttpPath true` |
 | Empty output / no auth | git version is older than 2.46 | Upgrade git |
+| `failed to store: -1` after successful operations (macOS) | Xcode's global `osxkeychain` helper runs alongside `nostr` and can't store the Nostr credential | Scope the helper to your relay URL — see [macOS](#macos-scope-the-helper-to-your-relay) |
 | `clock skew` / auth rejected | System clock is off by more than 60 s | Sync your system clock (`ntpdate`, `timedatectl`) |