An autonomous email-triage agent you deploy on a Debian VM in one command. It runs a reliable deterministic core out of the box, and gets smart when you connect your existing coding-agent subscription — Claude Code, Kimi Code, or Codex — with no API key.
Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ AGENT INBOX TRIAGE v1.0 │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────────┐ │
│ │ Ingestion │──▶│ Queue │──▶│ Dispatcher│──▶│ Executor │ │
│ │ (IMAP/API │ │ (SQLite) │ │(OODA loop)│ │ (LLM / ♞) │ │
│ │ /manual) │ └─────┬─────┘ └───────────┘ └────────┬─────────┘ │
│ └───────────┘ │ │ │
│ ┌──────┴──────┐ ┌──────┴────┐ │
│ │ Dead Letter │◀───────────────────│ Retry │ │
│ │ Queue │ (max 3 attempts) │ Policy │ │
│ └─────────────┘ └───────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Monitor │ │
│ │ (queue depth / dead-letter / stall / inbox backlog / alerts) │ │
│ └───────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
- Ingestion : cron, webhook, CLI (
agent.py enqueue), or IMAP adapter you add - Queue : SQLite locale par défaut, zero-config, zero-deps
- Dispatcher : boucle OODA — observe, oriente, décide, agit
- Executor : mode déterministe (♞) par défaut, mode LLM si CLI connectée
- Retry Policy : backoff exponentiel 10s → 60s → 600s
- Dead Letter : tâches en échec conservées, replayables
- Monitor : sondes intégrées, alertes configurables
One-shot install (Debian/Ubuntu)
unzip agent-inbox-v1.zip && cd agent-inbox-v1
sudo bash install.sh # system deps + venv + systemd service (enabled)
That's it. The agent starts as a systemd service (agent-inbox-v1), survives
reboots, and restarts on failure. Logs: journalctl -u agent-inbox-v1 -f.
No root / no systemd?
bash install.sh --no-servicesets up the venv, then runvenv/bin/python agent.py run.
Connect your LLM (optional, no API key)
install.sh auto-detects the first CLI it finds. Install & log in to one:
| CLI | Install | Connect |
|---|---|---|
| Claude Code | npm i -g @anthropic-ai/claude-code |
run claude, /login |
| Kimi Code | see platform.moonshot.ai | kimi-code |
| Codex | npm i -g @openai/codex |
codex login |
Force a specific one with PACK_LLM=claude|kimi|codex. If none is connected,
the agent still runs — see the honesty table below.
What's LLM vs deterministic (honest by design)
| Capability | Without an LLM CLI | With an LLM CLI connected |
|---|---|---|
| Queue, priorities, scheduling | ✅ deterministic | ✅ deterministic |
| Retry + exponential backoff | ✅ deterministic | ✅ deterministic |
| Dead-letter + replay | ✅ deterministic | ✅ deterministic |
| Dependencies (block on failed dep) | ✅ deterministic | ✅ deterministic |
| Idempotency (at-most-once key) | ✅ deterministic | ✅ deterministic |
| Email classification / drafting | built-in handlers (classify_email, draft_reply, archive_email, forward_email, extract_task) |
the LLM runs the Executor prompt (PROMPTS.md) on each task |
If a CLI is installed but not logged in, the agent logs a warning and falls back to the deterministic handler for that task — it never gets stuck.
Quick commands
python agent.py status
python agent.py enqueue --type classify_email --payload '{"from":"alice@example.com","subject":"Q2 invoice","body":"Please find the invoice attached."}'
python agent.py enqueue --type draft_reply --idempotency-key reply-2026-06-12
python agent.py run --once
python agent.py run --deterministic
python agent.py replay --task t-ab12cd34
bash smoke_test.sh
python EXAMPLE.py
Contents
| File | Purpose |
|---|---|
agent.py |
Runnable inbox triage agent — SQLite queue, retry, dead-letter, OODA, BYO-LLM wiring |
llm_adapter.py |
BYO-LLM CLI adapter (claude/kimi/codex), no API key |
install.sh |
One-shot Debian installer (deps + venv + systemd) |
agent-inbox-v1.service |
Reference systemd unit (install.sh generates the real one) |
smoke_test.sh / test_agent.py |
Offline test suite (deterministic) |
EXAMPLE.py |
End-to-end runnable demo of the shipped pipeline |
PROMPTS.md |
The Dispatcher / Executor / Monitor prompts the agent actually loads |
SOUL.md |
Agent identity, values, OODA loop |
SPEC.md |
Technical spec: task format, retry, scheduling, interfaces |
CHECKLIST.md |
Deployment checklist |
SUCCESS_METRICS.md |
KPI targets + failure definition |
OPERATING_COST_ESTIMATE.md |
LLM cost estimate (only relevant in LLM mode) |
requirements.txt |
Python deps (stdlib only) |
deploy.sh |
Thin wrapper → install.sh |