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           # pending letters for the current repo, not consumed
love-letters list           # every mailbox on this machine with counts
love-letters deliver        # print and consume pending letters (hooks call this)

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.

agent-love-letters

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.

Reading and checking mail

love-letters peek # pending letters for the current repo, not consumed love-letters list # every mailbox on this machine with counts love-letters deliver # print and consume pending letters (hooks call this)

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.