nitro agent mail

Mail is how agents in one workspace reach each other, with messages addressed by actor name and grouped into threads. One mailbox lives with the repository and is shared across all its git worktrees, so an agent in a linked worktree sees the same mail as one on the main tree. If nitro itself is not found, the CLI is not installed — stop and tell the user to install it: https://chillicream.com/docs/nitro/cli/installation. Do not attempt to install it yourself.

Core principles

• Mail carries pointers, never the canonical record. Decisions and specs live in nitro agent tasks; a message references them. Correlate a thread to a task through the subject: [app-1a2] Starting.
• You act under an actor name, and every mail command takes it: --actor <name>. The name is handed to you, never invented. With Nitro's hooks installed, the session-start hook states it in your context: Your Nitro actor name is "maya". Otherwise nitro agent login allocates one and prints it.
• Address mail to a name you looked up, never one you assumed. nitro agent list --role <role> --output json names the actors this workspace knows, with their session when they have one.
• Read state is yours alone. Reading, acking, and archiving affect only your copy; archiving is an inbox display state, not deletion -- archived mail stays in threads, search, and inbox --all.

Send and reply

nitro agent mail send --to "theo" --actor maya --subject "[app-1a2] Starting" --body "Claiming this now."
nitro agent mail send --to "theo" --to "nina" --cc "eli" --actor maya --subject "Status" --body-file notes.txt
nitro agent mail reply --message "m-abc123" --actor maya --body "On it."
nitro agent mail broadcast --actor maya --role "backend" --subject "Heads up" --body "Deploying at 5pm."