inboxd 1.0.11 → 1.0.12

package/.claude/skills/inbox-assistant/SKILL.md

@@ -67,6 +67,94 @@ Use when: Heavy inbox (>30 unread), user wants thoroughness, language like "what
 
 ---
 
+## Heavy Inbox Strategy
+
+When a user has a heavy inbox (>20 unread emails), use this optimized workflow:
+
+### 1. Quick Assessment
+
+```bash
+inbox summary --json
+```
+
+Identify which account(s) have the bulk of unread emails.
+
+### 2. Group Analysis First
+
+For heavy inboxes, **always start with grouped analysis**:
+
+```bash
+inbox 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):
+
+| Count | Sender Pattern | Likely Action |
+|-------|----------------|---------------|
+| 10+ | linkedin.com | Job alerts - offer batch delete |
+| 5+ | newsletter@ | Newsletters - offer unsubscribe + delete |
+| 5+ | noreply@ | Notifications - review, likely safe to batch |
+| 3+ | same domain | Check if promotional or transactional |
+
+**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.
+Delete all LinkedIn job alerts and old newsletters?
+```
+
+### 4. Find Stale Emails
+
+For cleanup of old emails, use server-side filtering:
+
+```bash
+inbox analyze --older-than 30d --group-by sender
+```
+
+Old emails (>30 days) are usually safe to batch delete:
+- Expired promotions
+- Delivered order notifications
+- Old newsletters
+
+### 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, newsletters, promos)
+    └── Then individual review of remaining
+```
+
+---
+
 ## Quick Start
 
 | Task | Command |
@@ -74,6 +162,8 @@ Use when: Heavy inbox (>30 unread), user wants thoroughness, language like "what
 | Check status | `inbox summary --json` |
 | Full triage | `inbox analyze --count 50` → classify → present |
 | Analyze by sender | `inbox analyze --count 50 --group-by sender` |
+| Find old emails | `inbox analyze --older-than 30d` |
+| Extract links from email | `inbox read --id <id> --links` |
 | Delete by ID | `inbox delete --ids "id1,id2" --confirm` |
 | Delete by sender | `inbox delete --sender "linkedin" --dry-run` → confirm → delete |
 | Delete by subject | `inbox delete --match "weekly digest" --dry-run` |
@@ -179,7 +269,12 @@ To stop: `launchctl unload ~/Library/LaunchAgents/com.yourname.inboxd.plist`
 | `inbox analyze --count 50` | Get email data for analysis | JSON array of email objects |
 | `inbox analyze --count 50 --all` | Include read emails | JSON array (read + unread) |
 | `inbox analyze --since 7d` | Only emails from last 7 days | JSON array (filtered by date) |
+| `inbox analyze --older-than 30d` | Only emails older than 30 days | JSON array (server-side filtered) |
 | `inbox analyze --group-by sender` | Group emails by sender domain | `{groups: [{sender, count, emails}], totalCount}` |
+| `inbox read --id <id>` | Read full email content | Email headers + body |
+| `inbox read --id <id> --links` | Extract links from email | List of URLs with optional link text |
+| `inbox read --id <id> --links --json` | Extract links as JSON | `{id, subject, from, linkCount, links}` |
+| `inbox search -q "query"` | Search using Gmail query syntax | JSON array of matching emails |
 | `inbox accounts` | List configured accounts | Account names and emails |
 
 ### Actions
@@ -276,8 +371,10 @@ Based on the summary stats, immediately suggest ONE clear next action:
 | One account has >50% of unread | "[account] has X of your Y unread—let me triage that first." |
 | Total unread ≤ 5 | "Only X unread—here's a quick summary:" (show inline) |
 | All accounts have 1-2 unread | "Light inbox day. Quick summary of all emails:" |
+| Total unread > 20 | "Heavy inbox. Let me group by sender to find batch cleanup opportunities." → `--group-by sender` |
 | Total unread > 30 | "Heavy inbox. I'll process by account, starting with [highest]." |
 | Single account with 0 unread | "Inbox zero on [account]! Want me to check the others?" |
+| Grouped analysis shows sender with 5+ emails | "[sender] has X emails. Delete them all?" |
 
 **Example good response:**
 ```
@@ -453,6 +550,8 @@ When user has job-related emails (LinkedIn, Indeed, recruiters) and wants to eva
 | "Delete [sender]'s emails" | Bulk sender cleanup | Two-step pattern with `--sender` filter |
 | "Delete the security emails" | Subject-based cleanup | `--match "security" --dry-run` → confirm → `--ids` |
 | "What senders have the most emails?" | Inbox analysis | `inbox analyze --group-by sender` |
+| "What links are in this email?" | Extract URLs | `inbox read --id <id> --links` |
+| "Find my old emails" / "Clean up old stuff" | Stale email review | `inbox analyze --older-than 30d` |
 | "I keep getting these" | Recurring annoyance | Suggest unsubscribe/filter, then delete batch |
 | "Check [specific account]" | Single-account focus | Skip other accounts entirely |
 | "Undo" / "Restore" | Recover deleted emails | `inbox restore --last N` |

package/CLAUDE.md

@@ -23,6 +23,7 @@ src/
 ├── gmail-monitor.js  # Gmail API: fetch, count, trash, restore
 ├── state.js          # Tracks seen emails per account
 ├── deletion-log.js   # Logs deleted emails for restore capability
+├── sent-log.js       # Logs sent emails for audit trail
 ├── notifier.js       # macOS notifications (node-notifier)
 └── skill-installer.js # Copies skill to ~/.claude/skills/
 
@@ -53,6 +54,7 @@ All user data lives in `~/.config/inboxd/`:
 | `token-<name>.json` | OAuth refresh/access tokens |
 | `state-<name>.json` | `{ seenEmailIds, lastCheck, lastNotifiedAt }` |
 | `deletion-log.json` | Audit log for deleted emails |
+| `sent-log.json` | Audit log for sent emails |
 
 ## Code Patterns
 
@@ -141,10 +143,16 @@ scripts/postinstall.js    # npm postinstall hint about install-skill
 | `inbox summary --json` | Quick status check (unread counts) |
 | `inbox analyze --count 50` | Get email data as JSON for classification |
 | `inbox analyze --group-by sender` | Group emails by sender domain |
+| `inbox analyze --older-than 30d` | Find emails older than 30 days (server-side filtering) |
 | `inbox delete --ids "id1,id2" --confirm` | Delete specific emails by ID |
 | `inbox delete --sender "pattern" --dry-run` | Preview deletion by sender filter |
 | `inbox delete --match "pattern" --dry-run` | Preview deletion by subject filter |
 | `inbox restore --last N` | Undo last N deletions |
+| `inbox read --id <id>` | Read full email content |
+| `inbox read --id <id> --links` | Extract links from email |
+| `inbox search -q <query>` | Search using Gmail query syntax |
+| `inbox send -t <to> -s <subj> -b <body> --confirm` | Send email (requires --confirm) |
+| `inbox reply --id <id> -b <body> --confirm` | Reply to email (requires --confirm) |
 | `inbox install-skill` | Install/update the Claude Code skill |
 
 ### Smart Filtering Options
@@ -156,6 +164,13 @@ scripts/postinstall.js    # npm postinstall hint about install-skill
 | `--force` | Override safety warnings (short patterns, large batches) |
 | `--dry-run` | Preview what would be deleted without deleting |
 
+### Send/Reply Safety
+The `send` and `reply` commands have built-in safety features:
+- **`--dry-run`**: Preview the email without sending
+- **`--confirm`**: Required flag to actually send (prevents accidental sends)
+- **Audit logging**: All sent emails are logged to `~/.config/inboxd/sent-log.json`
+- **Account resolution**: Prompts for account selection when multiple accounts exist
+
 ### Email Object Shape (from `analyze`)
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inboxd",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "CLI assistant for Gmail monitoring with multi-account support and AI-ready JSON output",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 
 const { program } = require('commander');
-const { getUnreadEmails, getEmailCount, trashEmails, getEmailById, untrashEmails, markAsRead, archiveEmails, groupEmailsBySender } = require('./gmail-monitor');
+const { getUnreadEmails, getEmailCount, trashEmails, getEmailById, untrashEmails, markAsRead, archiveEmails, groupEmailsBySender, getEmailContent, searchEmails, sendEmail, replyToEmail, extractLinks } = require('./gmail-monitor');
 const { getState, updateLastCheck, markEmailsSeen, getNewEmailIds, clearOldSeenEmails } = require('./state');
 const { notifyNewEmails } = require('./notifier');
 const { authorize, addAccount, getAccounts, getAccountEmail, removeAccount, removeAllAccounts, renameTokenFile, validateCredentialsFile, hasCredentials, isConfigured, installCredentials } = require('./gmail-auth');
 const { logDeletions, getRecentDeletions, getLogPath, readLog, removeLogEntries } = require('./deletion-log');
 const { getSkillStatus, checkForUpdate, installSkill, SKILL_DEST_DIR, SOURCE_MARKER } = require('./skill-installer');
+const { logSentEmail, getSentLogPath } = require('./sent-log');
 const readline = require('readline');
 const path = require('path');
 const os = require('os');
@@ -62,6 +63,61 @@ function parseSinceDuration(duration) {
   }
 }
 
+/**
+ * Parses a duration string for Gmail's older_than query
+ * Gmail only supports days (d) for older_than, so we convert weeks/months to days
+ * @param {string} duration - Duration string (e.g., "30d", "2w", "1m")
+ * @returns {string|null} Gmail query component (e.g., "30d") or null if invalid
+ */
+function parseOlderThanDuration(duration) {
+  const match = duration.match(/^(\d+)([dwm])$/i);
+  if (!match) {
+    return null;
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
+
+  switch (unit) {
+    case 'd': // days
+      return `${value}d`;
+    case 'w': // weeks -> days
+      return `${value * 7}d`;
+    case 'm': // months (approximate as 30 days)
+      return `${value * 30}d`;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Resolves the account to use, prompting user if ambiguous
+ * @param {string|undefined} specifiedAccount - Account specified via option
+ * @param {Object} chalk - Chalk instance for coloring
+ * @returns {{account: string|null, error: string|null}} Account name or error
+ */
+function resolveAccount(specifiedAccount, chalk) {
+  if (specifiedAccount) {
+    return { account: specifiedAccount, error: null };
+  }
+
+  const accounts = getAccounts();
+  if (accounts.length === 0) {
+    return { account: 'default', error: null };
+  }
+  if (accounts.length === 1) {
+    return { account: accounts[0].name, error: null };
+  }
+
+  // Multiple accounts, must specify
+  let errorMsg = chalk.yellow('Multiple accounts configured. Please specify --account <name>\n');
+  errorMsg += chalk.gray('Available accounts:\n');
+  accounts.forEach(a => {
+    errorMsg += chalk.gray(`  - ${a.name} (${a.email || 'unknown'})\n`);
+  });
+  return { account: null, error: errorMsg };
+}
+
 async function main() {
   const chalk = (await import('chalk')).default;
   const boxen = (await import('boxen')).default;
@@ -512,6 +568,7 @@ async function main() {
     .option('-n, --count <number>', 'Number of emails to analyze per account', '20')
     .option('--all', 'Include read and unread emails (default: unread only)')
     .option('--since <duration>', 'Only include emails from last N days/hours (e.g., "7d", "24h", "3d")')
+    .option('--older-than <duration>', 'Only include emails older than N days/weeks (e.g., "30d", "2w", "1m")')
     .option('--group-by <field>', 'Group emails by field (sender)')
     .action(async (options) => {
       try {
@@ -527,12 +584,34 @@ async function main() {
         const includeRead = !!options.all;
         let allEmails = [];
 
+        // Build Gmail query for --older-than (server-side filtering)
+        let olderThanQuery = null;
+        if (options.olderThan) {
+          const olderThanDays = parseOlderThanDuration(options.olderThan);
+          if (!olderThanDays) {
+            console.error(JSON.stringify({
+              error: `Invalid --older-than format: "${options.olderThan}". Use format like "30d", "2w", "1m"`
+            }));
+            process.exit(1);
+          }
+          olderThanQuery = `older_than:${olderThanDays}`;
+        }
+
         for (const account of accounts) {
-          const emails = await getUnreadEmails(account, maxPerAccount, includeRead);
+          let emails;
+          if (olderThanQuery) {
+            // Use searchEmails for server-side filtering when --older-than is specified
+            const query = includeRead
+              ? olderThanQuery
+              : `is:unread ${olderThanQuery}`;
+            emails = await searchEmails(account, query, maxPerAccount);
+          } else {
+            emails = await getUnreadEmails(account, maxPerAccount, includeRead);
+          }
           allEmails.push(...emails);
         }
 
-        // Filter by --since if provided
+        // Filter by --since if provided (client-side, for newer emails)
         if (options.since) {
           const sinceDate = parseSinceDuration(options.since);
           if (sinceDate) {
@@ -561,6 +640,288 @@ async function main() {
       }
     });
 
+  program
+    .command('read')
+    .description('Read full content of an email')
+    .requiredOption('--id <id>', 'Message ID to read')
+    .option('-a, --account <name>', 'Account name')
+    .option('--json', 'Output as JSON')
+    .option('--links', 'Extract and display links from email')
+    .action(async (options) => {
+      try {
+        const id = options.id.trim();
+        if (!id) {
+          console.log(chalk.yellow('No message ID provided.'));
+          return;
+        }
+
+        const { account, error } = resolveAccount(options.account, chalk);
+        if (error) {
+          console.log(error);
+          return;
+        }
+
+        // When --links is used, prefer HTML for better link extraction
+        const emailOptions = options.links ? { preferHtml: true } : {};
+        const email = await getEmailContent(account, id, emailOptions);
+
+        if (!email) {
+          console.log(chalk.red(`Email ${id} not found in account "${account}".`));
+          return;
+        }
+
+        // If --links flag is used, extract and display links
+        if (options.links) {
+          const links = extractLinks(email.body, email.mimeType);
+
+          if (options.json) {
+            console.log(JSON.stringify({
+              id: email.id,
+              subject: email.subject,
+              from: email.from,
+              linkCount: links.length,
+              links
+            }, null, 2));
+            return;
+          }
+
+          console.log(chalk.cyan('From: ') + chalk.white(email.from));
+          console.log(chalk.cyan('Subject: ') + chalk.white(email.subject));
+          console.log(chalk.gray('─'.repeat(50)));
+
+          if (links.length === 0) {
+            console.log(chalk.gray('No links found in this email.'));
+          } else {
+            console.log(chalk.bold(`\nLinks (${links.length}):\n`));
+            links.forEach((link, i) => {
+              if (link.text) {
+                console.log(chalk.white(`${i + 1}. ${link.text}`));
+                console.log(chalk.cyan(`   ${link.url}`));
+              } else {
+                console.log(chalk.cyan(`${i + 1}. ${link.url}`));
+              }
+            });
+          }
+          return;
+        }
+
+        if (options.json) {
+          console.log(JSON.stringify(email, null, 2));
+          return;
+        }
+
+        console.log(chalk.cyan('From: ') + chalk.white(email.from));
+        if (email.to) {
+          console.log(chalk.cyan('To: ') + chalk.white(email.to));
+        }
+        console.log(chalk.cyan('Date: ') + chalk.white(email.date));
+        console.log(chalk.cyan('Subject: ') + chalk.white(email.subject));
+        console.log(chalk.gray('─'.repeat(50)));
+        console.log(email.body || chalk.gray('(No content)'));
+        console.log(chalk.gray('─'.repeat(50)));
+
+      } catch (error) {
+        console.error(chalk.red('Error reading email:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('search')
+    .description('Search emails using Gmail query syntax')
+    .requiredOption('-q, --query <query>', 'Search query (e.g. "from:boss is:unread")')
+    .option('-a, --account <name>', 'Account to search')
+    .option('-n, --limit <number>', 'Max results', '20')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const { account, error } = resolveAccount(options.account, chalk);
+        if (error) {
+          console.log(error);
+          return;
+        }
+
+        const limit = parseInt(options.limit, 10);
+        const emails = await searchEmails(account, options.query, limit);
+
+        if (options.json) {
+          console.log(JSON.stringify(emails, null, 2));
+          return;
+        }
+
+        if (emails.length === 0) {
+          console.log(chalk.gray('No emails found matching query.'));
+          return;
+        }
+
+        console.log(chalk.bold(`Found ${emails.length} emails matching "${options.query}":\n`));
+
+        emails.forEach(e => {
+          const from = e.from.length > 35 ? e.from.substring(0, 32) + '...' : e.from;
+          const subject = e.subject.length > 50 ? e.subject.substring(0, 47) + '...' : e.subject;
+          console.log(chalk.cyan(e.id) + ' ' + chalk.white(from));
+          console.log(chalk.gray(`  ${subject}\n`));
+        });
+
+      } catch (error) {
+        console.error(chalk.red('Error searching emails:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('send')
+    .description('Send an email')
+    .requiredOption('-t, --to <email>', 'Recipient email')
+    .requiredOption('-s, --subject <subject>', 'Email subject')
+    .requiredOption('-b, --body <body>', 'Email body text')
+    .option('-a, --account <name>', 'Account to send from')
+    .option('--dry-run', 'Preview the email without sending')
+    .option('--confirm', 'Skip confirmation prompt')
+    .action(async (options) => {
+      try {
+        const { account, error } = resolveAccount(options.account, chalk);
+        if (error) {
+          console.log(error);
+          return;
+        }
+
+        // Get account email for display
+        const accountInfo = getAccounts().find(a => a.name === account);
+        const fromEmail = accountInfo?.email || account;
+
+        // Always show preview
+        console.log(chalk.bold('\nEmail to send:\n'));
+        console.log(chalk.cyan('From: ') + chalk.white(fromEmail));
+        console.log(chalk.cyan('To: ') + chalk.white(options.to));
+        console.log(chalk.cyan('Subject: ') + chalk.white(options.subject));
+        console.log(chalk.gray('─'.repeat(50)));
+        console.log(options.body);
+        console.log(chalk.gray('─'.repeat(50)));
+
+        if (options.dryRun) {
+          console.log(chalk.yellow('\nDry run: Email was not sent.'));
+          return;
+        }
+
+        if (!options.confirm) {
+          console.log(chalk.yellow('\nThis will send the email above.'));
+          console.log(chalk.gray('Use --confirm to skip this prompt, or --dry-run to preview without sending.\n'));
+          return;
+        }
+
+        console.log(chalk.cyan('\nSending...'));
+
+        const result = await sendEmail(account, {
+          to: options.to,
+          subject: options.subject,
+          body: options.body
+        });
+
+        if (result.success) {
+          // Log the sent email
+          logSentEmail({
+            account,
+            to: options.to,
+            subject: options.subject,
+            body: options.body,
+            id: result.id,
+            threadId: result.threadId
+          });
+
+          console.log(chalk.green(`\n✓ Email sent successfully!`));
+          console.log(chalk.gray(`  ID: ${result.id}`));
+          console.log(chalk.gray(`  Logged to: ${getSentLogPath()}`));
+        } else {
+          console.log(chalk.red(`\n✗ Failed to send email: ${result.error}`));
+          process.exit(1);
+        }
+      } catch (error) {
+        console.error(chalk.red('Error sending email:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('reply')
+    .description('Reply to an email')
+    .requiredOption('--id <id>', 'Message ID to reply to')
+    .requiredOption('-b, --body <body>', 'Reply body text')
+    .option('-a, --account <name>', 'Account to reply from')
+    .option('--dry-run', 'Preview the reply without sending')
+    .option('--confirm', 'Skip confirmation prompt')
+    .action(async (options) => {
+      try {
+        const { account, error } = resolveAccount(options.account, chalk);
+        if (error) {
+          console.log(error);
+          return;
+        }
+
+        // Fetch original email to show context
+        const original = await getEmailContent(account, options.id);
+        if (!original) {
+          console.log(chalk.red(`Email ${options.id} not found in account "${account}".`));
+          return;
+        }
+
+        // Build the subject we'll use
+        const replySubject = original.subject.toLowerCase().startsWith('re:')
+          ? original.subject
+          : `Re: ${original.subject}`;
+
+        // Show preview
+        console.log(chalk.bold('\nReply to:\n'));
+        console.log(chalk.gray('Original from: ') + chalk.white(original.from));
+        console.log(chalk.gray('Original subject: ') + chalk.white(original.subject));
+        console.log(chalk.gray('─'.repeat(50)));
+        console.log(chalk.bold('\nYour reply:\n'));
+        console.log(chalk.cyan('To: ') + chalk.white(original.from));
+        console.log(chalk.cyan('Subject: ') + chalk.white(replySubject));
+        console.log(chalk.gray('─'.repeat(50)));
+        console.log(options.body);
+        console.log(chalk.gray('─'.repeat(50)));
+
+        if (options.dryRun) {
+          console.log(chalk.yellow('\nDry run: Reply was not sent.'));
+          return;
+        }
+
+        if (!options.confirm) {
+          console.log(chalk.yellow('\nThis will send the reply above.'));
+          console.log(chalk.gray('Use --confirm to skip this prompt, or --dry-run to preview without sending.\n'));
+          return;
+        }
+
+        console.log(chalk.cyan('\nSending reply...'));
+
+        const result = await replyToEmail(account, options.id, options.body);
+
+        if (result.success) {
+          // Log the sent reply
+          logSentEmail({
+            account,
+            to: original.from,
+            subject: replySubject,
+            body: options.body,
+            id: result.id,
+            threadId: result.threadId,
+            replyToId: options.id
+          });
+
+          console.log(chalk.green(`\n✓ Reply sent successfully!`));
+          console.log(chalk.gray(`  ID: ${result.id}`));
+          console.log(chalk.gray(`  Logged to: ${getSentLogPath()}`));
+        } else {
+          console.log(chalk.red(`\n✗ Failed to send reply: ${result.error}`));
+          process.exit(1);
+        }
+      } catch (error) {
+        console.error(chalk.red('Error replying:'), error.message);
+        process.exit(1);
+      }
+    });
+
   program
     .command('delete')
     .description('Move emails to trash')