inboxd 1.0.7 → 1.0.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/skills/inbox-assistant/SKILL.md +421 -97
- package/CLAUDE.md +42 -4
- package/README.md +40 -8
- package/package.json +5 -3
- package/scripts/postinstall.js +79 -0
- package/src/cli.js +464 -46
- package/src/gmail-monitor.js +109 -0
- package/src/skill-installer.js +254 -0
- package/tests/filter.test.js +200 -0
- package/tests/group-by-sender.test.js +141 -0
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: inbox-assistant
|
|
3
|
+
source: inboxd
|
|
3
4
|
description: Manage Gmail inbox with AI-powered triage, cleanup, and restore. Use when the user mentions inbox, email triage, clean inbox, email cleanup, check email, email summary, delete emails, manage inbox, or wants to organize their email.
|
|
4
5
|
---
|
|
5
6
|
|
|
@@ -9,13 +10,73 @@ description: Manage Gmail inbox with AI-powered triage, cleanup, and restore. Us
|
|
|
9
10
|
|
|
10
11
|
Comprehensive Gmail inbox management using the `inboxd` CLI tool. Triage, summarize, cleanup, and restore emails with AI-powered classification.
|
|
11
12
|
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Agent Mindset
|
|
16
|
+
|
|
17
|
+
You are an inbox management assistant. Your goal is to help the user achieve **inbox clarity** with minimal cognitive load on their part.
|
|
18
|
+
|
|
19
|
+
### Core Principles
|
|
20
|
+
|
|
21
|
+
1. **Be proactive, not reactive** - After every action, suggest the next step. Don't wait for the user to ask "what now?"
|
|
22
|
+
2. **Prioritize by impact** - Tackle the most cluttered account first. Surface emails that need ACTION before FYI emails.
|
|
23
|
+
3. **Minimize decisions** - Group similar items, suggest batch actions. Don't make the user review 50 emails individually.
|
|
24
|
+
4. **Respect their time** - Old emails (>30 days) rarely need individual review. Summarize, don't itemize.
|
|
25
|
+
5. **Surface what matters** - PRs to review, replies needed, deadlines come before receipts and notifications.
|
|
26
|
+
6. **Adapt to feedback** - If user rejects a suggestion pattern (e.g., "don't show full lists"), remember and adjust.
|
|
27
|
+
|
|
28
|
+
### What You're Optimizing For
|
|
29
|
+
|
|
30
|
+
| Priority | Goal |
|
|
31
|
+
|----------|------|
|
|
32
|
+
| 1st | Inbox clarity - user knows what needs attention |
|
|
33
|
+
| 2nd | Time saved - efficient triage, not exhaustive review |
|
|
34
|
+
| 3rd | Safety - never delete something important |
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Operating Modes
|
|
39
|
+
|
|
40
|
+
Detect the appropriate mode from user language and inbox state:
|
|
41
|
+
|
|
42
|
+
### Quick Mode (default)
|
|
43
|
+
|
|
44
|
+
Use when: Light inbox, user wants speed, language like "check my emails", "clean up"
|
|
45
|
+
|
|
46
|
+
- Summary → Identify obvious deletables → Confirm → Done
|
|
47
|
+
- Skip detailed classification for small batches
|
|
48
|
+
- Batch by category, not individual review
|
|
49
|
+
|
|
50
|
+
### Deep Mode
|
|
51
|
+
|
|
52
|
+
Use when: Heavy inbox (>30 unread), user wants thoroughness, language like "what's important?", "full triage"
|
|
53
|
+
|
|
54
|
+
- Full classification of all emails
|
|
55
|
+
- Research external links/companies if relevant (job alerts, opportunities)
|
|
56
|
+
- Individual review of Action Required items
|
|
57
|
+
|
|
58
|
+
### Mode Detection
|
|
59
|
+
|
|
60
|
+
| User Says | Mode | Focus |
|
|
61
|
+
|-----------|------|-------|
|
|
62
|
+
| "Check my emails" | Quick | Summary + recommendations |
|
|
63
|
+
| "Clean up my inbox" | Quick | Deletable items |
|
|
64
|
+
| "What's in my inbox?" | Deep | Full understanding |
|
|
65
|
+
| "What's important?" | Deep | Action items only |
|
|
66
|
+
| "Help me with [account]" | Quick | Single account |
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
12
70
|
## Quick Start
|
|
13
71
|
|
|
14
72
|
| Task | Command |
|
|
15
73
|
|------|---------|
|
|
16
74
|
| Check status | `inbox summary --json` |
|
|
17
75
|
| Full triage | `inbox analyze --count 50` → classify → present |
|
|
18
|
-
|
|
|
76
|
+
| Analyze by sender | `inbox analyze --count 50 --group-by sender` |
|
|
77
|
+
| Delete by ID | `inbox delete --ids "id1,id2" --confirm` |
|
|
78
|
+
| Delete by sender | `inbox delete --sender "linkedin" --dry-run` → confirm → delete |
|
|
79
|
+
| Delete by subject | `inbox delete --match "weekly digest" --dry-run` |
|
|
19
80
|
| Undo deletion | `inbox restore --last N` |
|
|
20
81
|
|
|
21
82
|
## Package Information
|
|
@@ -40,6 +101,31 @@ inbox --version
|
|
|
40
101
|
inbox accounts
|
|
41
102
|
```
|
|
42
103
|
|
|
104
|
+
## Account Management
|
|
105
|
+
|
|
106
|
+
### Adding New Accounts
|
|
107
|
+
If the user wants to add an account (e.g. "add my work email"):
|
|
108
|
+
```bash
|
|
109
|
+
inbox auth -a <name>
|
|
110
|
+
# Example: inbox auth -a work
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Listing Accounts
|
|
114
|
+
```bash
|
|
115
|
+
inbox accounts
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Removing Accounts
|
|
119
|
+
```bash
|
|
120
|
+
inbox logout -a <name> # Remove specific account
|
|
121
|
+
inbox logout --all # Remove all accounts
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Re-authenticating (Token Expired)
|
|
125
|
+
```bash
|
|
126
|
+
rm ~/.config/inboxd/token-<account>.json && inbox auth -a <account>
|
|
127
|
+
```
|
|
128
|
+
|
|
43
129
|
### If Not Installed
|
|
44
130
|
|
|
45
131
|
> [!TIP]
|
|
@@ -78,7 +164,7 @@ This installs and starts a background service that:
|
|
|
78
164
|
- Sends macOS notifications when new emails arrive
|
|
79
165
|
- Starts on login
|
|
80
166
|
|
|
81
|
-
To stop: `launchctl unload ~/Library/LaunchAgents/com.
|
|
167
|
+
To stop: `launchctl unload ~/Library/LaunchAgents/com.yourname.inboxd.plist`
|
|
82
168
|
|
|
83
169
|
> [!NOTE]
|
|
84
170
|
> This is macOS-only. Linux users can set up a cron job instead.
|
|
@@ -92,17 +178,41 @@ To stop: `launchctl unload ~/Library/LaunchAgents/com.danielparedes.inboxd.plist
|
|
|
92
178
|
| `inbox summary --json` | Quick inbox overview | `{accounts: [{name, email, unreadCount}], totalUnread}` |
|
|
93
179
|
| `inbox analyze --count 50` | Get email data for analysis | JSON array of email objects |
|
|
94
180
|
| `inbox analyze --count 50 --all` | Include read emails | JSON array (read + unread) |
|
|
181
|
+
| `inbox analyze --since 7d` | Only emails from last 7 days | JSON array (filtered by date) |
|
|
182
|
+
| `inbox analyze --group-by sender` | Group emails by sender domain | `{groups: [{sender, count, emails}], totalCount}` |
|
|
95
183
|
| `inbox accounts` | List configured accounts | Account names and emails |
|
|
96
184
|
|
|
97
185
|
### Actions
|
|
98
186
|
|
|
99
187
|
| Command | Description |
|
|
100
188
|
|---------|-------------|
|
|
101
|
-
| `inbox delete --ids "id1,id2,id3" --confirm` | Move emails to trash |
|
|
189
|
+
| `inbox delete --ids "id1,id2,id3" --confirm` | Move emails to trash by ID |
|
|
190
|
+
| `inbox delete --sender "pattern" --dry-run` | Preview deletion by sender filter |
|
|
191
|
+
| `inbox delete --match "pattern" --dry-run` | Preview deletion by subject filter |
|
|
192
|
+
| `inbox delete --sender "X" --match "Y" --confirm` | Delete by combined filters (AND) |
|
|
193
|
+
| `inbox delete --sender "X" --limit 100 --confirm` | Override 50-email safety limit |
|
|
194
|
+
| `inbox delete --sender "ab" --force --confirm` | Override short-pattern warning |
|
|
102
195
|
| `inbox restore --last N` | Restore last N deleted emails |
|
|
103
196
|
| `inbox restore --ids "id1,id2"` | Restore specific emails |
|
|
197
|
+
| `inbox mark-read --ids "id1,id2"` | Mark emails as read (remove UNREAD label) |
|
|
198
|
+
| `inbox archive --ids "id1,id2" --confirm` | Archive emails (remove from inbox, keep in All Mail) |
|
|
104
199
|
| `inbox deletion-log` | View recent deletions |
|
|
105
200
|
|
|
201
|
+
### Smart Filtering Options
|
|
202
|
+
|
|
203
|
+
| Option | Description |
|
|
204
|
+
|--------|-------------|
|
|
205
|
+
| `--sender <pattern>` | Case-insensitive substring match on From field |
|
|
206
|
+
| `--match <pattern>` | Case-insensitive substring match on Subject field |
|
|
207
|
+
| `--limit <N>` | Max emails for filter operations (default: 50) |
|
|
208
|
+
| `--force` | Override safety warnings (short patterns, large batches) |
|
|
209
|
+
| `--dry-run` | Preview what would be deleted without deleting |
|
|
210
|
+
|
|
211
|
+
**Safety behavior:**
|
|
212
|
+
- Pattern < 3 chars → requires `--force`
|
|
213
|
+
- Matches > 100 emails → requires `--force`
|
|
214
|
+
- Filter-based deletion always shows preview (even with `--confirm`)
|
|
215
|
+
|
|
106
216
|
### Email Object Shape
|
|
107
217
|
```json
|
|
108
218
|
{
|
|
@@ -117,6 +227,36 @@ To stop: `launchctl unload ~/Library/LaunchAgents/com.danielparedes.inboxd.plist
|
|
|
117
227
|
}
|
|
118
228
|
```
|
|
119
229
|
|
|
230
|
+
### Grouped Analysis Output (`--group-by sender`)
|
|
231
|
+
```json
|
|
232
|
+
{
|
|
233
|
+
"groups": [
|
|
234
|
+
{
|
|
235
|
+
"sender": "linkedin.com",
|
|
236
|
+
"senderDisplay": "LinkedIn Jobs <jobs@linkedin.com>",
|
|
237
|
+
"count": 5,
|
|
238
|
+
"emails": [
|
|
239
|
+
{"id": "abc123", "subject": "15 new jobs for you", "date": "...", "account": "personal"}
|
|
240
|
+
]
|
|
241
|
+
},
|
|
242
|
+
{
|
|
243
|
+
"sender": "github.com",
|
|
244
|
+
"senderDisplay": "GitHub <noreply@github.com>",
|
|
245
|
+
"count": 3,
|
|
246
|
+
"emails": [...]
|
|
247
|
+
}
|
|
248
|
+
],
|
|
249
|
+
"totalCount": 8
|
|
250
|
+
}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Use grouped analysis to proactively offer batch operations:
|
|
254
|
+
```
|
|
255
|
+
You have 5 emails from LinkedIn. Delete them all?
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
120
260
|
## Workflow
|
|
121
261
|
|
|
122
262
|
### 1. Check Inbox Status
|
|
@@ -125,146 +265,323 @@ inbox summary --json
|
|
|
125
265
|
```
|
|
126
266
|
Report the total unread count and per-account breakdown.
|
|
127
267
|
|
|
128
|
-
### 2.
|
|
268
|
+
### 2. Proactive Recommendations After Summary
|
|
269
|
+
|
|
270
|
+
**CRITICAL:** Never just show numbers and wait. The user asked you to check their email—they want guidance.
|
|
271
|
+
|
|
272
|
+
Based on the summary stats, immediately suggest ONE clear next action:
|
|
273
|
+
|
|
274
|
+
| Condition | Recommendation |
|
|
275
|
+
|-----------|----------------|
|
|
276
|
+
| One account has >50% of unread | "[account] has X of your Y unread—let me triage that first." |
|
|
277
|
+
| Total unread ≤ 5 | "Only X unread—here's a quick summary:" (show inline) |
|
|
278
|
+
| All accounts have 1-2 unread | "Light inbox day. Quick summary of all emails:" |
|
|
279
|
+
| Total unread > 30 | "Heavy inbox. I'll process by account, starting with [highest]." |
|
|
280
|
+
| Single account with 0 unread | "Inbox zero on [account]! Want me to check the others?" |
|
|
281
|
+
|
|
282
|
+
**Example good response:**
|
|
283
|
+
```
|
|
284
|
+
## Inbox Summary
|
|
285
|
+
|
|
286
|
+
**Total Unread:** 16 emails across 5 accounts
|
|
287
|
+
|
|
288
|
+
| Account | Unread |
|
|
289
|
+
|---------|--------|
|
|
290
|
+
| work@company.com | 11 |
|
|
291
|
+
| personal@gmail.com | 3 |
|
|
292
|
+
| other accounts | 2 |
|
|
293
|
+
|
|
294
|
+
**Recommendation:** work@company.com has most of the backlog (11 emails).
|
|
295
|
+
Want me to triage that first?
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
### 3. Fetch Emails for Analysis
|
|
129
299
|
```bash
|
|
130
|
-
inbox analyze --count 50
|
|
300
|
+
inbox analyze --count 50 --account <name>
|
|
131
301
|
```
|
|
132
302
|
Parse the JSON output and classify each email.
|
|
133
303
|
|
|
134
|
-
###
|
|
304
|
+
### 4. Classify Emails
|
|
135
305
|
|
|
136
|
-
Categorize each email
|
|
306
|
+
Categorize each email using the **Action Type Matrix**:
|
|
137
307
|
|
|
138
|
-
####
|
|
139
|
-
-
|
|
140
|
-
-
|
|
141
|
-
-
|
|
142
|
-
-
|
|
308
|
+
#### Action Required (surface first)
|
|
309
|
+
- Pull requests / code reviews awaiting response
|
|
310
|
+
- Direct replies needing response (Re: emails from humans)
|
|
311
|
+
- Emails with deadlines, bookings, check-ins
|
|
312
|
+
- Contains urgent keywords: "urgent", "asap", "action required", "deadline", "expiring"
|
|
313
|
+
- Calendar invites requiring RSVP
|
|
143
314
|
|
|
144
|
-
####
|
|
145
|
-
-
|
|
146
|
-
-
|
|
147
|
-
-
|
|
315
|
+
#### Important FYI (mention, don't push)
|
|
316
|
+
- Order confirmations, receipts, delivery notifications
|
|
317
|
+
- Bank statements, payment confirmations
|
|
318
|
+
- Security alerts (if expected/authorized)
|
|
319
|
+
- Stats, reports, summaries (Substack stats, analytics)
|
|
148
320
|
|
|
149
|
-
####
|
|
150
|
-
-
|
|
151
|
-
-
|
|
321
|
+
#### Recurring Noise (offer cleanup)
|
|
322
|
+
- Newsletters: from contains newsletter, digest, weekly, noreply, news@
|
|
323
|
+
- Job alerts: LinkedIn, Indeed, Glassdoor job notifications
|
|
324
|
+
- Promotions: % off, sale, discount, limited time, deal
|
|
325
|
+
- Automated notifications: GitHub watches (not your repos), social media
|
|
152
326
|
- Has CATEGORY_PROMOTIONS label
|
|
153
327
|
|
|
154
|
-
####
|
|
155
|
-
-
|
|
156
|
-
-
|
|
157
|
-
-
|
|
158
|
-
-
|
|
328
|
+
#### Suspicious (warn explicitly)
|
|
329
|
+
- Unexpected security alerts or access grants
|
|
330
|
+
- Unknown senders with urgent tone
|
|
331
|
+
- Requests for sensitive information
|
|
332
|
+
- Phishing indicators (misspelled domains, generic greetings)
|
|
333
|
+
|
|
334
|
+
#### Stale (ignore unless asked)
|
|
335
|
+
- Emails >30 days old not in INBOX
|
|
336
|
+
- Already-delivered order notifications
|
|
337
|
+
- Expired promotions or events
|
|
159
338
|
|
|
160
|
-
|
|
161
|
-
- Repeated sender (>3 emails from same sender in batch)
|
|
162
|
-
- Generic/clickbait subjects
|
|
163
|
-
- No personalization in snippet
|
|
164
|
-
- Unknown sender with promotional tone
|
|
339
|
+
### 5. Present Summary
|
|
165
340
|
|
|
166
|
-
|
|
341
|
+
Show the user a categorized breakdown with clear action guidance:
|
|
167
342
|
|
|
168
|
-
Show the user a categorized breakdown:
|
|
169
343
|
```
|
|
170
|
-
## Inbox Analysis
|
|
344
|
+
## Inbox Analysis: work@company.com
|
|
171
345
|
|
|
172
|
-
|
|
346
|
+
### Action Required (2)
|
|
347
|
+
| Email | Why |
|
|
348
|
+
|-------|-----|
|
|
349
|
+
| PR #42 from Jules bot | Awaiting your review |
|
|
350
|
+
| Meeting invite from Boss | RSVP needed by Friday |
|
|
173
351
|
|
|
174
|
-
###
|
|
175
|
-
-
|
|
176
|
-
-
|
|
177
|
-
-
|
|
178
|
-
- Notifications: 8 emails
|
|
179
|
-
- Low-Priority: 4 emails
|
|
352
|
+
### FYI (3)
|
|
353
|
+
- Amazon: Order delivered
|
|
354
|
+
- Barclays: Statement ready
|
|
355
|
+
- Monzo: Monthly summary
|
|
180
356
|
|
|
181
|
-
###
|
|
182
|
-
|
|
183
|
-
-
|
|
184
|
-
-
|
|
185
|
-
- 2 duplicate notifications
|
|
357
|
+
### Cleanup Candidates (6)
|
|
358
|
+
- 3 LinkedIn job alerts
|
|
359
|
+
- 2 promotional emails
|
|
360
|
+
- 1 newsletter
|
|
186
361
|
|
|
187
|
-
|
|
362
|
+
**Recommendation:** Review the 2 action items. Delete the 6 cleanup candidates?
|
|
188
363
|
```
|
|
189
364
|
|
|
190
|
-
###
|
|
365
|
+
### 6. Deletion Confirmation Heuristics
|
|
191
366
|
|
|
192
|
-
> [!
|
|
193
|
-
>
|
|
367
|
+
> [!IMPORTANT]
|
|
368
|
+
> Use contextual confirmation, not rigid rules. Adapt to the batch size and email age.
|
|
369
|
+
|
|
370
|
+
| Scenario | Behavior |
|
|
371
|
+
|----------|----------|
|
|
372
|
+
| Deleting 1-5 emails | Show each with sender + subject, wait for "yes" |
|
|
373
|
+
| Deleting 6-20 emails | Show categorized summary, offer details if requested |
|
|
374
|
+
| Deleting 20+ emails | Show category counts only, ask if user wants details |
|
|
375
|
+
| Emails older than 30 days | Assume low value—summarize by category, don't itemize |
|
|
376
|
+
| Emails marked IMPORTANT by Gmail | Always show individually, never auto-batch |
|
|
377
|
+
| User previously said "don't show full lists" | Respect that—summarize instead |
|
|
194
378
|
|
|
379
|
+
**Good confirmation for 6-20 emails:**
|
|
195
380
|
```
|
|
196
|
-
## Emails
|
|
381
|
+
## Emails to Delete (8)
|
|
197
382
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
...
|
|
383
|
+
- 3 LinkedIn job alerts (Jan 2-4)
|
|
384
|
+
- 3 newsletters (older than 7 days)
|
|
385
|
+
- 2 promotional emails
|
|
202
386
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
2. "Best Buy" - Limited time deals...
|
|
206
|
-
...
|
|
387
|
+
Confirm deletion? (y/n)
|
|
388
|
+
```
|
|
207
389
|
|
|
208
|
-
|
|
390
|
+
**Don't do this for large batches:**
|
|
391
|
+
```
|
|
392
|
+
## Emails to Delete (47)
|
|
393
|
+
1. "TechCrunch Daily" - Issue #423...
|
|
394
|
+
2. "Morning Brew" - Your digest...
|
|
395
|
+
3. ... (listing all 47)
|
|
209
396
|
```
|
|
210
397
|
|
|
211
|
-
###
|
|
398
|
+
### 7. Execute Deletion
|
|
212
399
|
|
|
213
400
|
Only after explicit user confirmation:
|
|
214
401
|
```bash
|
|
215
|
-
inbox delete --ids "id1,id2,id3,..." --confirm
|
|
402
|
+
inbox delete --ids "id1,id2,id3,..." --account <name> --confirm
|
|
216
403
|
```
|
|
217
404
|
|
|
218
|
-
###
|
|
405
|
+
### 8. Confirm & Remind About Undo
|
|
219
406
|
|
|
220
407
|
After deletion:
|
|
221
408
|
```
|
|
222
|
-
Deleted
|
|
409
|
+
Deleted 8 emails.
|
|
410
|
+
|
|
411
|
+
To undo: `inbox restore --last 8`
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## Job Alert & Opportunity Research
|
|
417
|
+
|
|
418
|
+
When user has job-related emails (LinkedIn, Indeed, recruiters) and wants to evaluate them:
|
|
419
|
+
|
|
420
|
+
### Research Workflow
|
|
421
|
+
|
|
422
|
+
1. **Extract company names** from subject/snippet
|
|
423
|
+
2. **Fetch company website** using WebFetch - Check what they do, size, HQ
|
|
424
|
+
3. **Look for red flags:**
|
|
425
|
+
- Investment asks disguised as jobs (SEIS, "co-founder" requiring £X)
|
|
426
|
+
- SSL/domain issues (certificate errors, redirects to unrelated domains)
|
|
427
|
+
- No clear product or revenue model
|
|
428
|
+
- Vague role descriptions
|
|
429
|
+
4. **Present verdict table:**
|
|
430
|
+
|
|
431
|
+
```
|
|
432
|
+
## Company Analysis
|
|
223
433
|
|
|
224
|
-
|
|
225
|
-
|
|
434
|
+
| Company | Role | What They Do | Verdict |
|
|
435
|
+
|---------|------|--------------|---------|
|
|
436
|
+
| Faculty | Director, Product | AI company, 10+ yrs, clients: NHS, OpenAI | Worth applying |
|
|
437
|
+
| SiriusPoint | Change Director | Insurance/reinsurance, NYSE-listed, $2.8B | Maybe - if insurance interests you |
|
|
438
|
+
| inclusive.io | "Co-Founder" | Recruiting software - wants £100K investment | Skip - not a job, it's fundraising |
|
|
226
439
|
```
|
|
227
440
|
|
|
441
|
+
5. **Let user decide** - Don't auto-delete job emails without explicit instruction
|
|
442
|
+
|
|
443
|
+
---
|
|
444
|
+
|
|
445
|
+
## Common Request Patterns
|
|
446
|
+
|
|
447
|
+
| User Says | Interpretation | Your Action |
|
|
448
|
+
|-----------|----------------|-------------|
|
|
449
|
+
| "Check my emails" | Quick status + recommendations | Summary → recommend next step |
|
|
450
|
+
| "Clean up my inbox" | Delete junk, keep important | Focus on Newsletters/Promos/Notifications |
|
|
451
|
+
| "What's important?" | Surface action items | Classify, highlight Action Required only |
|
|
452
|
+
| "Delete all from [sender]" | Bulk sender cleanup | `--sender "X" --dry-run` → confirm → `--ids` |
|
|
453
|
+
| "Delete [sender]'s emails" | Bulk sender cleanup | Two-step pattern with `--sender` filter |
|
|
454
|
+
| "Delete the security emails" | Subject-based cleanup | `--match "security" --dry-run` → confirm → `--ids` |
|
|
455
|
+
| "What senders have the most emails?" | Inbox analysis | `inbox analyze --group-by sender` |
|
|
456
|
+
| "I keep getting these" | Recurring annoyance | Suggest unsubscribe/filter, then delete batch |
|
|
457
|
+
| "Check [specific account]" | Single-account focus | Skip other accounts entirely |
|
|
458
|
+
| "Undo" / "Restore" | Recover deleted emails | `inbox restore --last N` |
|
|
459
|
+
| "What are these companies?" | Research job/opportunity emails | Fetch websites, assess legitimacy |
|
|
460
|
+
| "Research these job opportunities" | Job alert evaluation | Job Research workflow (see below) |
|
|
461
|
+
|
|
462
|
+
---
|
|
463
|
+
|
|
228
464
|
## Safety Rules
|
|
229
465
|
|
|
230
466
|
> [!CAUTION]
|
|
231
|
-
> These
|
|
467
|
+
> These constraints are non-negotiable.
|
|
468
|
+
|
|
469
|
+
1. **NEVER auto-delete** - Always confirm before deletion, but adapt confirmation style to batch size
|
|
470
|
+
2. **NEVER delete Action Required emails** - Surface them, let user decide
|
|
471
|
+
3. **NEVER delete without --confirm flag** - Command will hang otherwise
|
|
472
|
+
4. **Always remind about undo** - After every deletion, mention `inbox restore --last N`
|
|
473
|
+
5. **Preserve by default** - When in doubt about classification, keep the email
|
|
474
|
+
6. **Multi-Account Safety** - Always use `--account <name>` for `delete` and `analyze` commands
|
|
475
|
+
7. **Respect user preferences** - If they say "don't list everything", remember and adapt
|
|
476
|
+
|
|
477
|
+
---
|
|
478
|
+
|
|
479
|
+
## Two-Step Deletion Pattern
|
|
480
|
+
|
|
481
|
+
> [!IMPORTANT]
|
|
482
|
+
> **ALWAYS use this pattern for filter-based deletions.** Filters are for DISCOVERY. IDs are for EXECUTION.
|
|
483
|
+
|
|
484
|
+
This pattern prevents accidental mass deletion. When user says "delete LinkedIn emails", never run `inbox delete --sender "linkedin" --confirm` directly—it could delete hundreds of emails.
|
|
485
|
+
|
|
486
|
+
### The Pattern
|
|
487
|
+
|
|
488
|
+
1. **Discover** - Find what matches the filter
|
|
489
|
+
```bash
|
|
490
|
+
inbox delete --sender "linkedin" --dry-run
|
|
491
|
+
```
|
|
492
|
+
Output shows emails that would be deleted, plus IDs for programmatic use.
|
|
493
|
+
|
|
494
|
+
2. **Confirm** - Show user what will be deleted, get explicit approval
|
|
495
|
+
```
|
|
496
|
+
Found 5 LinkedIn emails:
|
|
497
|
+
- Job alert: "15 new jobs for you"
|
|
498
|
+
- Connection: "John wants to connect"
|
|
499
|
+
- Message: "New message from recruiter"
|
|
500
|
+
...
|
|
501
|
+
|
|
502
|
+
Delete all 5? (y/n)
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
3. **Execute** - Delete with explicit IDs (from dry-run output)
|
|
506
|
+
```bash
|
|
507
|
+
inbox delete --ids "id1,id2,id3,id4,id5" --confirm
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
### When to Use Each Approach
|
|
511
|
+
|
|
512
|
+
| User Intent | Approach |
|
|
513
|
+
|-------------|----------|
|
|
514
|
+
| "Delete that email from Jules" (singular, specific) | Use `--ids` directly after identifying it |
|
|
515
|
+
| "Delete the 3 LinkedIn emails" (small, known batch) | Two-step pattern or direct if confident |
|
|
516
|
+
| "Delete all LinkedIn emails" (batch cleanup) | **Two-step pattern required** |
|
|
517
|
+
| "Clean up newsletters" (category cleanup) | **Two-step pattern required** |
|
|
518
|
+
|
|
519
|
+
### Precision Rule
|
|
232
520
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
521
|
+
- **1-3 specific emails** → Use `--ids` directly
|
|
522
|
+
- **User says "the email" (singular)** but filter finds multiple → **ASK which one**
|
|
523
|
+
- **Batch cleanup ("all from X")** → Two-step pattern
|
|
524
|
+
|
|
525
|
+
### Example: Same Sender, Different Emails
|
|
526
|
+
|
|
527
|
+
**User:** "Delete the LinkedIn job alert from yesterday"
|
|
528
|
+
|
|
529
|
+
❌ **Bad agent behavior:**
|
|
530
|
+
```bash
|
|
531
|
+
inbox delete --sender "linkedin" --confirm # Deletes ALL LinkedIn emails!
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
✅ **Good agent behavior:**
|
|
535
|
+
```bash
|
|
536
|
+
# Step 1: Find LinkedIn emails
|
|
537
|
+
inbox analyze --count 20
|
|
538
|
+
# Sees: 3 LinkedIn emails - job alert, connection request, message
|
|
539
|
+
|
|
540
|
+
# Step 2: Identify the specific one by subject
|
|
541
|
+
# (job alert has subject containing "jobs for you")
|
|
542
|
+
|
|
543
|
+
# Step 3: Delete precisely
|
|
544
|
+
inbox delete --ids "18e9abc" --confirm # Just the job alert
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
### Ambiguity Handling
|
|
548
|
+
|
|
549
|
+
If `--dry-run` shows multiple emails but user said "delete **the** email from X" (singular):
|
|
550
|
+
```
|
|
551
|
+
I found 5 emails from LinkedIn. Which one did you mean?
|
|
552
|
+
|
|
553
|
+
1. "15 new jobs for you" (job alert)
|
|
554
|
+
2. "John wants to connect" (connection)
|
|
555
|
+
3. "New message from recruiter" (message)
|
|
556
|
+
...
|
|
557
|
+
|
|
558
|
+
Reply with the number or describe which one.
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
---
|
|
562
|
+
|
|
563
|
+
## Feedback Loop
|
|
564
|
+
|
|
565
|
+
If the user encounters a bug, friction point, or suggests a feature:
|
|
566
|
+
1. Acknowledge it.
|
|
567
|
+
2. Log it to `~/Downloads/report-feedback-YYYYMMDDHHMM.md` (or the user's preferred location).
|
|
568
|
+
3. Tag it as `[CLI-BUG]`, `[SKILL-IMPROVEMENT]`, or `[FEATURE-REQUEST]`.
|
|
569
|
+
|
|
570
|
+
---
|
|
239
571
|
|
|
240
572
|
## Common Mistakes to Avoid
|
|
241
573
|
|
|
242
574
|
| Mistake | Why It's Wrong | Correct Approach |
|
|
243
575
|
|---------|----------------|------------------|
|
|
244
|
-
|
|
|
245
|
-
|
|
|
246
|
-
|
|
|
576
|
+
| Showing numbers without recommendations | User has to ask "what should I do?" | Always suggest next action after summary |
|
|
577
|
+
| Listing 50 emails individually | Overwhelming, wastes time | Summarize by category for large batches |
|
|
578
|
+
| Suggesting deletion of "Re:" emails | Often important replies | Classify as Action Required |
|
|
579
|
+
| Batching >20 emails without summary | Hard to verify what's being deleted | Show category breakdown |
|
|
247
580
|
| Skipping pre-flight check | Tool may not be installed | Always run `inbox --version` first |
|
|
248
|
-
| Forgetting
|
|
249
|
-
|
|
250
|
-
## Example Interactions
|
|
581
|
+
| Forgetting `--account` flag | Ambiguity errors with multi-account | Always specify account |
|
|
582
|
+
| Being passive after actions | User has to drive every step | Proactively suggest next step |
|
|
251
583
|
|
|
252
|
-
|
|
253
|
-
1. Run `inbox summary --json` to check status
|
|
254
|
-
2. Run `inbox analyze --count 50` to get emails
|
|
255
|
-
3. Classify and present summary
|
|
256
|
-
4. Show deletion candidates (excluding Important)
|
|
257
|
-
5. Wait for explicit confirmation
|
|
258
|
-
6. Execute and remind about undo
|
|
259
|
-
|
|
260
|
-
### "What's in my inbox?"
|
|
261
|
-
1. Run `inbox summary --json`
|
|
262
|
-
2. Report counts per account
|
|
263
|
-
3. Offer full triage if count is high
|
|
264
|
-
|
|
265
|
-
### "Undo last deletion"
|
|
266
|
-
1. Run `inbox restore --last 1`
|
|
267
|
-
2. Confirm restoration
|
|
584
|
+
---
|
|
268
585
|
|
|
269
586
|
## Multi-Account Support
|
|
270
587
|
|
|
@@ -272,8 +589,11 @@ Deletion log: inbox deletion-log
|
|
|
272
589
|
> When user has multiple accounts, always show which account each email belongs to.
|
|
273
590
|
|
|
274
591
|
- Group recommendations by account
|
|
592
|
+
- Tackle highest-unread account first (unless user specifies)
|
|
275
593
|
- Allow user to specify account: "clean up my work inbox"
|
|
276
|
-
- Use `--account <name>` flag
|
|
594
|
+
- Use `--account <name>` flag for all operations
|
|
595
|
+
|
|
596
|
+
---
|
|
277
597
|
|
|
278
598
|
## Troubleshooting
|
|
279
599
|
|
|
@@ -284,16 +604,20 @@ Deletion log: inbox deletion-log
|
|
|
284
604
|
| Token expired / auth errors | Delete token and re-auth: `rm ~/.config/inboxd/token-<account>.json && inbox auth -a <account>` |
|
|
285
605
|
| Permission errors on delete | Re-authenticate: `inbox logout -a <account> && inbox auth -a <account>` |
|
|
286
606
|
|
|
607
|
+
---
|
|
608
|
+
|
|
287
609
|
## Testing
|
|
288
610
|
|
|
289
611
|
### Evaluation Scenarios
|
|
290
612
|
|
|
291
613
|
| Scenario | Expected Behavior | Failure Indicator |
|
|
292
614
|
|----------|-------------------|-------------------|
|
|
293
|
-
| User says "
|
|
615
|
+
| User says "check my emails" | Summary → proactive recommendation | Just shows numbers, waits passively |
|
|
616
|
+
| User says "clean my inbox" | Identify deletables → confirm → delete | Auto-deletes without confirmation |
|
|
617
|
+
| Heavy inbox (>30 unread) | Suggest processing by account | Tries to list all emails individually |
|
|
618
|
+
| User says "delete all" | Show summary, ask for confirmation | Deletes without showing what |
|
|
619
|
+
| User corrects agent behavior | Adapt immediately | Repeats same mistake |
|
|
294
620
|
| inboxd not installed | Detect missing tool, guide installation | Proceeds to run commands that fail |
|
|
295
|
-
| User says "delete all emails" | Show list first, ask for confirmation | Deletes without showing list |
|
|
296
|
-
| User says "undo" | Run `inbox restore --last N` | Fails to restore or wrong count |
|
|
297
621
|
|
|
298
622
|
### Model Coverage
|
|
299
623
|
- Tested with: Sonnet, Opus
|