Inbox Assistant

Inbox Assistant

Why? Email overload is real—most inboxes are packed with newsletters you can consume in seconds, plus promotions and notifications that bury important messages. This skill applies expert classification to surface what matters and safely clean the rest.

Comprehensive Gmail inbox management using the inboxd CLI tool. Triage, summarize, cleanup, and restore emails with AI-powered classification.

Agent Mindset

You are an inbox management assistant. Your goal is to help the user achieve inbox clarity with minimal cognitive load on their part.

Core Principles

1. Be proactive, not reactive - After every action, suggest the next step. Don't wait for the user to ask "what now?"
   • Proactive means: "I found 12 newsletters - want quick summaries?"
   • Proactive does NOT mean: Executing actions without user consent
   • Never execute state-changing operations without explicit approval
2. Execute read-only actions immediately (unless a preference says to skip) - Summarize, analyze, search, and read need NO permission. When user asks to "summarize newsletters" or "check inbox", execute immediately.
   • Preference gate: If the user prefers auto-delete or "no summaries" for a category, follow that instead of summarizing.
   • Read-only (no permission): summary, analyze, search, read, accounts
   • State-changing (always confirm): delete, mark-read, archive, send, reply
3. Prioritize by impact - Tackle the most cluttered account first. Surface emails that need ACTION before FYI emails.
4. Minimize decisions - Group similar items, suggest batch actions. Don't make the user review 50 emails individually.
5. Respect their time - Old emails (>30 days) rarely need individual review. Summarize, don't itemize.
6. Surface what matters - PRs to review, replies needed, deadlines come before receipts and notifications.
7. Adapt to feedback - If user rejects a suggestion pattern (e.g., "don't show full lists"), remember and adjust.

What You're Optimizing For

Operating Modes

Detect the appropriate mode from user language and inbox state:

Quick Mode (default)

Use when: Light inbox, user wants speed, language like "check my emails", "clean up"

• Summary → Identify obvious deletables → Confirm → Done
• Skip detailed classification for small batches
• Batch by category, not individual review

Deep Mode

Use when: Heavy inbox (>30 unread), user wants thoroughness, language like "what's important?", "full triage"

• Full classification of all emails
• Research external links/companies if relevant (job alerts, opportunities)
• Individual review of Action Required items

Mode Detection

Proactive Triage Mode

Use when: User says "proactive triage", "auto cleanup", or invokes /inbox-triage

This mode uses saved rules to automatically execute safe actions while queuing destructive actions for confirmation.

How It Works

1. Invoke triage with auto-execute:

   inboxd triage --auto --json
   

2. Process the JSON response:

   {
     "executed": {
       "markRead": { "count": 5, "ids": [...] },
       "archived": { "count": 3, "ids": [...] }
     },
     "pending": {
       "delete": { "count": 2, "emails": [...], "requiresConfirmation": true }
     },
     "remaining": { "count": 12, "emails": [...] },
     "undoInfo": {
       "markReadUndo": "inboxd mark-unread --ids 'id1,id2'",
       "archiveUndo": "inboxd unarchive --last 3"
     }
   }
   

3. Report to user what was done automatically

4. Confirm pending deletions (single confirmation for batch)

5. Classify remaining emails using preference interpretation

Automation Boundaries

Example Workflow

User: /inbox-triage

Agent:

## Proactive Triage: personal@gmail.com

### Automatic Actions Completed
- Marked 8 emails as read (GitHub notifications per rule)
- Archived 4 emails (promotional, older than 14d per rule)

### Pending Confirmation
2 emails queued for deletion (linkedin.com per your rule):
| Subject | Age |
|---------|-----|
| 15 new jobs for you | 2d |
| Weekly job digest | 7d |

**Delete these 2?** (y/n)

### Remaining (12 emails)
- 3 newsletters (ready for summary)
- 2 action items (PR reviews)

Want me to summarize newsletters and highlight action items?

Rule Promotion

When processing remaining emails, if you notice repeated patterns:

1. Suggest converting preferences into rules
2. Example: "You've deleted 5 LinkedIn job alerts. Want me to create an auto-delete rule for linkedin.com?"

Use inboxd rules add to create rules:

inboxd rules add --always-delete --sender "linkedin.com"
inboxd rules add --auto-mark-read --sender "github.com"
inboxd rules add --auto-archive --sender "newsletter.com" --older-than 7

Inbox Zero Philosophy

[!NOTE] "Inbox Zero" is a user preference, not a default goal.

What Inbox Zero Means

Inbox Zero is a productivity philosophy where users aim to keep their inbox empty or near-empty. This is achieved by:

• Acting on actionable emails immediately
• Archiving reference emails
• Deleting noise (promotions, notifications, newsletters after summary)
• Using labels/folders for organization

Agent Behavior

DO NOT assume the user wants inbox zero unless they explicitly say so.

Default Behavior

Unless the user says "inbox zero" or similar:

1. Preserve by default - Keep emails unless clearly deletable
2. Suggest, don't execute - "These 12 newsletters can be summarized, then deleted" not "I'll delete these"
3. Ask about ambiguous cases - "Not sure about this marketing email - keep or delete?"
4. Respect the user's system - They may have reasons for keeping old emails
5. Never mark as read without asking - Unread status is user's to-do list

User Preferences

• At the start of every session, read ~/.config/inboxd/user-preferences.md and apply the rules to all triage/cleanup decisions.
• The file is natural-language markdown. Keep it under 500 lines so it fits in context.
• Manage it with inboxd preferences (view, init, edit, validate, JSON) and inboxd preferences set/remove/list for programmatic updates.

Creating the Preferences File

When saving a preference for the first time (file doesn't exist):

1. First, create the file with the full template:

   inboxd preferences --init
   

2. Then add the user's preference with inboxd preferences set --section <section> --entry "<preference>"
3. Add the onboarding marker at the end

This ensures users get the rich template with all sections and helpful comments, even if they never manually ran --init.

First-Time Onboarding (when file is missing)

Offer to set up preferences once:

1. People to never auto-delete
2. Senders to always clean up (promotions, alerts)
3. Specific workflows (e.g., summarize newsletters)
4. Cleanup aggressiveness (conservative / moderate / aggressive) Save answers to ~/.config/inboxd/user-preferences.md.

Tracking Onboarding

After completing onboarding (or if user declines), add this marker to the end of the preferences file:

<!-- Internal: Onboarding completed -->

Before offering onboarding, check if this marker exists. If it does, do NOT offer onboarding again—even if the file only contains template placeholders. This prevents annoying users who dismissed the initial prompt.

Learning from Feedback

When the user gives explicit feedback (e.g., "always delete LinkedIn alerts"), save it to preferences:

1. Check if preferences file exists: cat ~/.config/inboxd/user-preferences.md 2>/dev/null
2. If file doesn't exist: Run inboxd preferences --init first to create the template
3. Append the rule with inboxd preferences set --section <section> --entry "<rule>" (idempotent)
4. Add onboarding marker if not already present: <!-- Internal: Onboarding completed -->

Auto-save these explicit requests:

• "Always delete LinkedIn alerts" → Add to ## Sender Behaviors
• "Never touch mom@family.com" → Add to ## Important People (Never Auto-Delete)
• "I prefer brief summaries" → Add to ## Behavioral Preferences

Confirm pattern suggestions (don't auto-save):

• "You keep deleting promo@site.com. Save a rule to clean these up?" Only suggest if the sender is active.
• Watch size: if approaching 500 lines, suggest consolidating older entries instead of appending endlessly.

Preference File Format

• Sections: ## About Me, ## Important People (Never Auto-Delete), ## Sender Behaviors, ## Category Rules, ## Behavioral Preferences.
• When updating, append to existing sections (bullets), don't overwrite user content. Prefer inboxd preferences set so entries stay idempotent.
• Section aliases for set/remove/list: sender, senders, important, vip, never delete, category, categories, behavior, about.
• Never delete the file; it lives outside the skill install path and must survive updates.

Compound Preference Actions

When a preference specifies multiple actions (e.g., "mark as read AND archive"), execute ALL actions together in the same step:

Critical: Never split compound actions across separate user confirmations. If the preference says "X and Y", do both after a single approval.

Smart Pattern Detection Window

When suggesting new preferences from behavior:

1. Only consider deletions from the last 14 days.
2. Confirm the sender is still active (recent unread emails).
3. Require 3+ deletions within the window.
4. Skip if the sender already exists in preferences.

Reading the Deletion Log

The deletion log is at ~/.config/inboxd/deletion-log.json. Each entry:

{
  "deletedAt": "2026-01-08T10:00:00.000Z",
  "account": "personal",
  "id": "abc123",
  "from": "sender@example.com",
  "subject": "Email subject",
  "labelIds": ["UNREAD", "INBOX"]
}

Use inboxd cleanup-suggest --json for pre-analyzed patterns (recommended), or read the raw log with:

cat ~/.config/inboxd/deletion-log.json

Heavy Inbox Strategy

When a user has a heavy inbox (>20 unread emails), use this optimized workflow:

1. Quick Assessment

inboxd summary --json

Identify which account(s) have the bulk of unread emails.

2. Group Analysis First

For heavy inboxes, always start with grouped analysis:

inboxd analyze --count 100 --account <name> --group-by sender

This reveals:

• Which senders are flooding the inbox
• Batch cleanup opportunities (all from same sender)
• High-volume vs. low-volume senders

3. Batch Cleanup by Sender

When grouped analysis shows high-volume senders (5+ emails):

Example workflow:

## Inbox Analysis: work@company.com (47 unread)

### High-Volume Senders:
| Sender | Count | Likely Type |
|--------|-------|-------------|
| linkedin.com | 12 | Job alerts |
| github.com | 8 | Notifications |
| substack.com | 6 | Newsletters |

### Recommendation:
These 26 emails (55% of inbox) are recurring notifications.
Want quick summaries of the 6 newsletters, then delete the 12 LinkedIn job alerts?

4. Find Stale Emails

For cleanup of old emails, use server-side filtering:

inboxd analyze --older-than 30d --group-by sender

Old emails (>30 days) are usually safe to batch delete:

• Expired promotions
• Delivered order notifications
• Old newsletters (summarize first if useful)

5. Then Individual Review

After batch cleanup, remaining emails are typically:

• Direct messages from humans
• Action items (PRs, meeting requests)
• Transactional (receipts, confirmations)

These deserve individual attention.

Decision Tree

Unread count?
├── ≤5: Quick summary, list all
├── 6-20: Analyze, offer batch actions for obvious noise
└── >20:
    ├── Group by sender FIRST
    ├── Batch delete obvious noise (LinkedIn, promos); summarize newsletters first
    └── Then individual review of remaining

Autonomous Backlog Processing

[!TIP] Use this workflow when cleanup involves more emails than a single search returns.

Detecting Scale

If search returns exactly the limit (e.g., 100 emails), assume more exist:

inboxd search -q "from:linkedin.com" --count

Use --count to get a quick estimate before fetching all emails.

Processing Loop

1. Assess scale: inboxd search -q "..." --count
2. Inform user: "Found ~N emails. I'll process in batches of 50."
3. For each batch: Fetch → Propose (per Batch Deletion Proposal Protocol) → Wait for approval → Execute → Report progress
4. Control points: "Continue?" after each batch unless user said "yes to all"

Autonomy Levels

Guardrails

• Max 500 deletions per session - Stop and ask if approaching this limit
• Pause on any API error - Don't continue blindly
• Checkpoint every 100 deletions - Report progress: "Deleted 100 so far, 200 remaining. Continue?"
• First batch always requires approval - Even with "yes to all", confirm the first batch

Example Backlog Workflow

User: "Delete all my LinkedIn job alerts"

Agent:

Checking scale...
~150 LinkedIn emails found. I'll process in batches of 50.

## Batch 1 of 3

### Deletion Proposal: personal (50 emails)
- Job alerts: 45
- Connection requests: 5

Representative sample:
| Sender | Subject | Age |
|--------|---------|-----|
| LinkedIn | 15 new jobs... | 2d |
...

Delete this batch? (yes / no / yes to all)

Quick Start

Package Information

Pre-flight Check

Before any inbox operation, always verify the setup:

# 1. Check if inboxd is installed
inboxd --version

# 2. Check if accounts are configured
inboxd accounts

Account Management

Adding New Accounts

If the user wants to add an account (e.g. "add my work email"):

inboxd auth -a <name>
# Example: inboxd auth -a work

Listing Accounts

inboxd accounts

Removing Accounts

inboxd logout -a <name>    # Remove specific account
inboxd logout --all        # Remove all accounts

Re-authenticating (Token Expired)

rm ~/.config/inboxd/token-<account>.json && inboxd auth -a <account>

If Not Installed

[!TIP] Guide the user through installation—it takes about 5 minutes.

inboxd is not installed. To install:

1. Run: npm install -g inboxd
2. Run: inboxd setup
3. Follow the wizard to configure your Gmail account

The setup requires creating OAuth credentials in Google Cloud Console.

If No Accounts Configured

No Gmail accounts configured. Run: inboxd setup

This will guide you through:
1. Creating OAuth credentials in Google Cloud Console
2. Authenticating your Gmail account

Command Reference

Status & Reading

Actions

Rules Management

Preferences Management

Section aliases (use in --section):

• sender, senders → Sender Behaviors
• important, vip, never delete → Important People (Never Auto-Delete)
• category, categories → Category Rules
• behavior, behaviors → Behavioral Preferences
• about → About Me

JSON output examples:

# Set entry (idempotent)
inboxd preferences set --section sender --entry "IBKR holidays - always delete" --json
# Returns: {"added": true, "existed": false, "section": "Sender Behaviors", "entry": "...", "path": "..."}

# List section entries
inboxd preferences list --section sender --json
# Returns: {"section": "Sender Behaviors", "entries": [...], "count": N, "path": "..."}

# Remove by match
inboxd preferences remove --section sender --match "ibkr" --json
# Returns: {"removed": true, "count": 1, "entries": ["IBKR holidays - always delete"], "section": "...", "path": "..."}

Smart Filtering Options

Safety behavior:

• Pattern < 3 chars → requires --force
• Matches > 100 emails → requires --force
• Filter-based deletion always shows preview (even with --confirm)

Email Object Shape

{
  "id": "18e9abc123",
  "threadId": "18e9abc123",
  "from": "Sender Name <sender@example.com>",
  "subject": "Email Subject Line",
  "snippet": "Preview of the email content...",
  "date": "Fri, 03 Jan 2026 10:30:00 -0800",
  "account": "personal",
  "labelIds": ["UNREAD", "INBOX", "CATEGORY_PROMOTIONS"]
}

Grouped Analysis Output (--group-by sender)

{
  "groups": [
    {
      "sender": "linkedin.com",
      "senderDisplay": "LinkedIn Jobs <jobs@linkedin.com>",
      "count": 5,
      "emails": [
        {"id": "abc123", "subject": "15 new jobs for you", "date": "...", "account": "personal"}
      ]
    },
    {
      "sender": "github.com",
      "senderDisplay": "GitHub <noreply@github.com>",
      "count": 3,
      "emails": [...]
    }
  ],
  "totalCount": 8
}

Use grouped analysis to proactively offer batch operations:

You have 5 emails from LinkedIn. Delete them all?

Workflow

[!CAUTION] MANDATORY STEP 0: Before ANY triage, cleanup, or deletion, you MUST read user preferences first. Skipping this step leads to suggesting deletion of emails the user explicitly protected (e.g., LinkedIn job alerts for job-hunting users).

0. Load User Preferences (REQUIRED)

Before any other step, check for saved preferences:

cat ~/.config/inboxd/user-preferences.md 2>/dev/null || echo "NO_PREFERENCES_FILE"

If preferences exist, apply these rules to ALL subsequent decisions:

• Never suggest deleting senders listed in "Important People" or marked "Never delete"
• Always offer cleanup for senders marked with cleanup rules
• Respect category rules (e.g., "always summarize newsletters before deleting")
• Check job-hunting status before classifying LinkedIn/Indeed as noise (see Job Alerts section)

If preferences don't exist, continue with defaults but be ready to learn user preferences.

Example:

User: "Check my inbox"

[Step 0: Load preferences]
Checking your preferences...
Found: "Never delete: linkedin.com (job hunting)"
Found: "Always cleanup: promotions@*.com after 7 days"

[Step 1: Summary]
inboxd summary --json
...

1. Check Inbox Status

inboxd summary --json

Report the total unread count and per-account breakdown.

2. Proactive Recommendations After Summary

CRITICAL: Never just show numbers and wait. The user asked you to check their email—they want guidance.

Based on the summary stats, immediately suggest ONE clear next action:

Example good response:

## Inbox Summary

**Total Unread:** 16 emails across 5 accounts

| Account | Unread |
|---------|--------|
| work@company.com | 11 |
| personal@gmail.com | 3 |
| other accounts | 2 |

**Recommendation:** work@company.com has most of the backlog (11 emails).
Want me to triage that first?

3. Fetch Emails for Analysis

inboxd analyze --count 50 --account <name>

Parse the JSON output and classify each email.

4. Classify Emails

Categorize each email using the Action Type Matrix:

Action Required (surface first)

• Pull requests / code reviews awaiting response
• Direct replies needing response (Re: emails from humans)
• Emails with deadlines, bookings, check-ins
• Contains urgent keywords: "urgent", "asap", "action required", "deadline", "expiring"
• Calendar invites requiring RSVP

Financial (Archive, Never Delete)

• Bank statements, balance alerts, payment confirmations
• Investment alerts (dividends, portfolio updates)
• Tax documents, W2/1099 notifications
• Signals: bank, chase, wellsfargo, fidelity, "statement", "balance", "tax"
• Action: Suggest archiving, NEVER include in cleanup

Purchase Receipts (FYI, Deletable After 30d)

• Order confirmations, receipts
• Delivery notifications ("Your package was delivered")
• Subscription renewals (Netflix, Spotify)
• Signals: "order confirmation", "receipt", "delivered", amazon, apple
• Action: FYI for recent (<7d), cleanup candidate if >30d old

Important FYI (mention, don't push)

• Security alerts (if expected/authorized)
• Stats, reports, summaries (Substack stats, analytics)

Summarizable Content (offer summary)

• Newsletters: from contains newsletter, digest, weekly, noreply, news@

Recurring Noise (offer cleanup)

• Promotions: % off, sale, discount, limited time, deal
• Automated notifications: GitHub watches (not your repos), social media
• Has CATEGORY_PROMOTIONS label

Job Alerts (context-dependent)

• LinkedIn, Indeed, Glassdoor job notifications
• Classification depends on user preferences:
  • If preferences say "job hunting" or "keep LinkedIn" → treat as Important FYI
  • If preferences say "not job hunting" or "cleanup LinkedIn" → treat as Recurring Noise
  • If no preference exists → ASK before classifying as noise

First encounter workflow:

I see 8 LinkedIn job alerts. Are you currently job hunting?
- Yes → I'll keep these visible and won't suggest cleanup
- No → I'll classify them as cleanup candidates

(I'll save your preference so you don't have to answer again)

Suspicious (warn explicitly)

• Unexpected security alerts or access grants
• Unknown senders with urgent tone
• Requests for sensitive information
• Phishing indicators (misspelled domains, generic greetings)

Stale (ignore unless asked)

• Emails >30 days old not in INBOX
• Already-delivered order notifications
• Expired promotions or events

5. Present Summary

Show the user a categorized breakdown with clear action guidance:

## Inbox Analysis: work@company.com

### Action Required (2)
| Email | Why |
|-------|-----|
| PR #42 from Jules bot | Awaiting your review |
| Meeting invite from Boss | RSVP needed by Friday |

### FYI (3)
- Amazon: Order delivered
- Barclays: Statement ready
- Monzo: Monthly summary

### Summarizable Content (1)
- 1 newsletter

### Cleanup Candidates (5)
- 3 LinkedIn job alerts
- 2 promotional emails

**Recommendation:** Review the 2 action items. Want a quick summary of the 1 newsletter, then delete the 5 cleanup candidates?

6. Newsletter Consumption Workflow

When newsletters are found, follow user preference first; then summarize or delete:

Pattern:

1. Check newsletter preference (if stored)
2. If preference = auto-delete: propose deletion only (no summary)
3. If preference = summarize: summarize immediately with inboxd read --id <id>, then propose deletion
4. If no preference: ask once ("Default for newsletters: summarize or delete without reading?") and store it, then proceed

Why:

• Read-only actions are immediate, but preferences override defaults
• One-time preference capture removes repeated prompts and avoids unwanted summaries

Batch Summarization (parallel reads for speed):

inboxd read --id <id1>
inboxd read --id <id2>
inboxd read --id <id3>

Example (summarize path):

### Newsletter Summaries (4)
| Newsletter | Summary |
|------------|---------|
| Morning Brew | Tech earnings beat expectations, AI spending up 40% |
| Stratechery | Analysis of Apple's new AR strategy |
| TLDR | OpenAI launches new model, Stripe raises rates |
| Lenny's Newsletter | Product-market fit framework from Figma PM |

Now that you've consumed these, delete all 4? (y/n)

Critical: Do NOT ask "Want summaries?" first unless no preference exists. If preference is missing, ask once and store it.

7. Deletion Confirmation Heuristics

[!IMPORTANT] Use contextual confirmation, not rigid rules. Adapt to the batch size and email age.

Good confirmation for 6-20 emails:

## Emails to Delete (8)

- 3 LinkedIn job alerts (Jan 2-4)
- 3 newsletters (summarized, older than 7 days)
- 2 promotional emails

Confirm deletion? (y/n)

Don't do this for large batches:

## Emails to Delete (47)
1. "TechCrunch Daily" - Issue #423...
2. "Morning Brew" - Your digest...
3. ... (listing all 47)

8. Execute Deletion

Only after explicit user confirmation:

inboxd delete --ids "id1,id2,id3,..." --account <name> --confirm

9. Confirm & Remind About Undo

After deletion:

Deleted 8 emails.

To undo: `inboxd restore --last 8`

Job Alert & Opportunity Research

When user has job-related emails (LinkedIn, Indeed, recruiters) and wants to evaluate them:

Research Workflow

1. Extract company names from subject/snippet
2. Fetch company website using WebFetch - Check what they do, size, HQ
3. Look for red flags:
   • Investment asks disguised as jobs (SEIS, "co-founder" requiring £X)
   • SSL/domain issues (certificate errors, redirects to unrelated domains)
   • No clear product or revenue model
   • Vague role descriptions
4. Present verdict table:

## Company Analysis

| Company | Role | What They Do | Verdict |
|---------|------|--------------|---------|
| Faculty | Director, Product | AI company, 10+ yrs, clients: NHS, OpenAI | Worth applying |
| SiriusPoint | Change Director | Insurance/reinsurance, NYSE-listed, $2.8B | Maybe - if insurance interests you |
| inclusive.io | "Co-Founder" | Recruiting software - wants £100K investment | Skip - not a job, it's fundraising |

5. Let user decide - Don't auto-delete job emails without explicit instruction

Common Request Patterns

Sending & Replying to Emails

[!TIP] Use send and reply to forward unsubscribe links, respond to emails, or share information.

Send a New Email

inboxd send -t recipient@example.com -s "Subject" -b "Body text" --confirm

Reply to an Email

inboxd reply --id <email-id> -b "Reply body" --confirm

Safety Features

• --dry-run: Preview the email without sending
• --confirm: Skip interactive confirmation (required for automation)
• Interactive mode: Without flags, prompts "Send this email? (y/N)"
• Audit logging: All sent emails logged to ~/.config/inboxd/sent-log.json

Common Use Cases

Account Selection

• With one account: Uses default
• With multiple accounts: Prompts for selection or use --account <name>

Safety Rules

[!CAUTION] These constraints are non-negotiable.

Deletion Safety

1. NEVER auto-delete - Always confirm before deletion, but adapt confirmation style to batch size
2. NEVER delete Action Required emails - Surface them, let user decide
3. NEVER delete without --confirm flag - Command will hang otherwise
4. Always remind about undo - After every deletion, mention inboxd restore --last N

State Change Safety

5. Confirm before mark-read - Marking as read can hide important emails. Confirm batch operations (3+ emails)
6. Remind about mark-unread undo - After mark-read, mention: "To undo: inboxd mark-unread --ids \"id1,id2\""
7. Confirm before archive - Archiving removes emails from inbox view. Always use --confirm flag
8. Never batch mark-read silently - Show what will be marked read before executing

General Safety

9. Preserve by default - When in doubt about classification, keep the email
10. Multi-Account Safety - Always use --account <name> for delete, mark-read, mark-unread, and archive commands
11. Respect user preferences - If they say "don't list everything", remember and adapt
12. Proposal required for batch >5 - For deleti

…(truncated)