agent-mailbox

A desktop task inbox for coding agents. It turns natural-language requests (from you, Claude Code, Codex, or any agent) into recoverable, handoff-able, archivable Markdown task objects. It is a task ledger and reflection layer — not an executor: it never runs your tasks, it just keeps their state straight so any agent can pick up where the last one left off.

Why

When multiple agents (or sessions) work on the same machine, the hard part is recovering context on handoff — what's active, what's blocked, what's queued. agent-mailbox keeps a rolling current-handoff.md panel and a triage/queue/blocked state machine so a fresh agent can resume in one command.

Install

git clone https://github.com/SDDbb/agent-mailbox
cd agent-mailbox
./install.sh          # installs the CLI + a user systemd timer for periodic reflection

Then copy config.example.toml to ~/.config/agent-mailbox/config.toml and edit the paths (or rely on the working-directory defaults).

Commands

agent-mailbox submit "refactor the auth module"   # capture a task
agent-mailbox triage                              # sort inbox -> triage/queue/blocked
agent-mailbox list                                # show all tasks by status
agent-mailbox show <id>                           # inspect one task
agent-mailbox move <id> <status>                  # move a task between states
agent-mailbox reflect                             # refresh the rolling handoff panel
agent-mailbox pickup                              # one-shot resume: active/blocked/queue/inbox snapshot
agent-mailbox handoff                             # print the current handoff panel
agent-mailbox scan-workspace --target <dir>       # shallow-scan a reference project into triage candidates
agent-mailbox digest-scan <file> --write-cards    # distill scan findings into reviewable note drafts

Status directories

Tasks live as Markdown files under mailbox_root, one directory per state: inbox → triage → queue → active / blocked → archive (plus outbox for reflections and deadletter).

Design boundaries

• Never executes. The mailbox records and organizes; agents/humans do the work.
• Sensitive tasks stay local. Tasks containing secrets (token/password/key/cookie/…) are never sent to a model — they go straight to blocked and are flagged.
• Cheap by default. Triage/reflect/distill route to a cheap LLM via the cheap-llm-router CLI; a local model may only act as a low-risk pre-filter.

Optional: distill to a notes vault

When a task is archived, agent-mailbox can distill a one-line draft note into a staging area of a Markdown vault (e.g. Obsidian) for human review before promotion — the machine only nominates; you decide what becomes a real note. Configure with vault_root / card_inbox_subdir / distill_on_archive, or disable it entirely.

License

Apache-2.0