| name | ephemeral-identity |
| description | Mint and use a throwaway agent-mail identity when you are a one-off agent with no registered persona but still need to send, receive, and reply to mail. Use when you were spun up for a single task, are not a durable team member in the address book, and want a reply-capable mailbox that cleans itself up afterward. |
| allowed-tools | bash read |
Ephemeral Identity
Get a reply-capable agent-mail identity without registering a durable persona.
When to use
You're a short-lived agent — spawned for one task, a sub-job, or an experiment — and you need to coordinate over agent-mail, but you don't have (and shouldn't create) a permanent entry in the address book. An ephemeral identity gives you a real, reply-capable mailbox that auto-prunes after it goes idle, so you can participate in threads and then disappear without leaving clutter behind.
If you already resolve to a durable persona via agent-mail persona current, use that instead — durable identities are for ongoing team members. Ephemeral identities are for agents that won't be around tomorrow.
1. Mint your identity
NAME=$(agent-mail ephemeral new --label "spec reviewer for PR 42")
echo "I am $NAME"
ephemeral new prints the bare generated name (like eph-20260622-amber-lynx) to stdout, so command substitution captures it cleanly; human-readable detail goes to stderr. The name is auto-generated — you can't choose it. Add --role "..." to record what you are, or --for-path DIR to bind it to a directory other than the current one.
2. Adopt it for the session
Export it so the normal mail skills resolve to it without passing --persona every time:
export AGENT_MAIL_PERSONA="$NAME"
Now send-mail, check-mail, and reply-mail work exactly as documented — they pick up your identity from the environment. If you can't rely on the environment persisting across separate commands, thread the name explicitly instead: --persona "$NAME" on each call (no identity files are written either way, so nothing gets clobbered).
3. Use it
Send, check your inbox, and reply with the normal skills — you are a first-class recipient and sender. A teammate can reply to you by your eph-… name and it lands in your inbox.
agent-mail send --from "$NAME" --to project-lead \
--subject "Review findings for PR 42" \
--body "Two issues in the auth middleware — details below." --json
agent-mail count --persona "$NAME" --new-only --json
Durable personas and groups always win name resolution, so your ephemeral name never shadows a real teammate.
4. Clean up when done
Your identity self-prunes after it goes idle past the TTL (default 7 days; configurable), so doing nothing is a valid choice for truly one-off work. To tear it down immediately:
agent-mail ephemeral rm "$NAME"
--trash (macOS) moves it to the Trash so it's recoverable instead of being deleted outright.--keep-archive retains just the transcript (an inert folder you remove manually later).
Tear down explicitly when you've finished a task and want the mailbox gone now; leave it to auto-prune when a late reply might still be worth receiving.
Inspecting ephemerals
agent-mail who "$NAME" --json
agent-mail who --path "$(pwd)" --json
The default agent-mail who listing never shows ephemerals — they stay out of the durable roster by design.
