| name | agent-love-letters |
| description | Send a one-shot letter to agents working in another repo on this machine, delivered when their next session starts. Use when the user says "send a letter to <repo>", "leave a note for the <project> agents", "tell the <other repo>'s agent about this", or wants a point picked up next time someone works in another local project. |
agent-love-letters
love-letters is a CLI that carries messages between coding agents in different repos on the same machine. A letter you send is injected into the context of the next agent session that starts in the recipient repo, once, then archived.
Sending a letter
Resolve the CLI in this order: love-letters on PATH, then npx -y agent-love-letters.
love-letters send --to <recipient-repo-path> --subject "<short subject>" <<'EOT'
<the letter body>
EOT
--to takes any path inside the recipient repo. Ask the user for the path if you cannot infer it; do not guess between similarly named directories.- The sender defaults to the current repo, which is how the recipient knows where the letter came from. Pass
--from <path> only when writing on another repo's behalf.
- Sending needs no setup and does not modify any configuration.
Write the body for an agent with zero context on the current conversation. State the fact or request concretely, name files and commands with full paths, and say what prompted the letter. One topic per letter; send two letters rather than one letter with two topics.
Reading and checking mail
love-letters peek
love-letters list
love-letters deliver
Do not run deliver casually: it consumes the letters, and the session-start hook will then have nothing to inject. Use peek to look.
Receiving (one-time setup)
Delivery requires a session-start hook. If the user asks why letters are not arriving, or wants a machine set up to receive:
- Machine-wide, all harnesses: the user runs
love-letters install all themselves (it edits ~/.claude/settings.json, ~/.codex/hooks.json, and ~/.pi/agent/extensions; agents should not modify those files).
- Single repo, Claude Code only: run
love-letters install claude --project in that repo. This writes .claude/settings.json in the working tree, which the user reviews like any other edit.
love-letters uninstall all reverses the machine-wide setup.
