wtf is agent-love-letters?

agent-love-letters is a small tool that lets AI coding agents leave messages for other AI coding agents working in different projects on the same computer. If you are working with an agent in one repository and want to warn another project about something, like a security fix or a change in setup, you can ask your current agent to send a letter to that other repo. The next time an agent session starts there, whether it is Claude Code, Codex, or a tool called pi, the message is automatically added to that session's context. Each letter is delivered exactly once. It shows up the first time a new session starts in the target repository, marked clearly as a note left by an agent working elsewhere on the machine, and is not shown again in later sessions. Messages include who sent them, when, and a subject line, and multiple pending letters for the same repo are all delivered together. Setting it up takes two steps. First, on your machine, you install the tool globally and run a setup command that wires a session start hook into the coding agent harnesses you use, which lets that machine receive letters. Second, you install a matching skill into each agent you use through a separate skills tool, which teaches those agents how to send letters. Only the receiving step needs to be done once per machine, sending needs no extra setup after that. You can also scope receiving to a single project instead of the whole machine by writing the hook into that project's own settings file, which is safe to commit alongside your code. Behind the scenes, letters are stored as small markdown files inside a per recipient folder, organized using the target repository's real file path so subfolders of the same repo share one mailbox. Delivering a letter simply moves its file into a delivered folder, which is what keeps it from showing up twice. The README includes a clear security warning: because letters are inserted into an agent's context without filtering, anything with permission to write into the letters folder can effectively give instructions to your agents, so the tool is only as safe as the other processes running on your machine. The project requires Node.js version 18 or newer and includes a test suite that runs against temporary files rather than your real configuration.