synap 0.1.0 → 0.3.0

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

@@ -67,6 +67,7 @@ Detect user intent and respond appropriately:
 |------|---------|
 | Capture idea | `synap add "your thought here"` |
 | Add todo | `synap todo "task description"` |
+| Add todo with due date | `synap todo "Review PR #42" --due tomorrow` |
 | Add question | `synap question "what you're wondering"` |
 | List active | `synap list` |
 | See all | `synap list --all` |
@@ -98,6 +99,7 @@ Quick capture of a thought.
 ```bash
 synap add "What if we used a graph database?"
 synap add "Need to review the API design" --type todo --priority 1
+synap add "Prep for demo" --type todo --due 2025-02-15
 synap add "Meeting notes from standup" --type note --tags "meetings,weekly"
 synap add --type project --title "Website Redesign" "Complete overhaul of the marketing site..."
 ```
@@ -108,6 +110,7 @@ synap add --type project --title "Website Redesign" "Complete overhaul of the ma
 - `--priority <1|2|3>`: 1=high, 2=medium, 3=low
 - `--tags <tags>`: Comma-separated tags
 - `--parent <id>`: Parent entry ID
+- `--due <date>`: Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)
 - `--json`: JSON output
 
 #### `synap todo <content>`
@@ -118,6 +121,8 @@ synap todo "Review PR #42"
 # Equivalent to: synap add "Review PR #42" --type todo
 ```
 
+Options: `--priority`, `--tags`, `--parent`, `--due`, `--json`
+
 #### `synap question <content>`
 Shorthand for adding a question.
 
@@ -126,6 +131,8 @@ synap question "Should we migrate to TypeScript?"
 # Equivalent to: synap add "..." --type question
 ```
 
+Options: `--priority`, `--tags`, `--parent`, `--due`, `--json`
+
 ### Query Commands
 
 #### `synap list`
@@ -139,6 +146,9 @@ synap list --status raw                 # Needs triage
 synap list --priority 1                 # High priority only
 synap list --tags work,urgent           # Has ALL specified tags
 synap list --since 7d                   # Created in last 7 days
+synap list --overdue                    # Overdue entries
+synap list --due-before 7d              # Due in next 7 days
+synap list --has-due                    # Entries with due dates
 synap list --json                       # JSON output for parsing
 ```
 
@@ -150,11 +160,16 @@ synap list --json                       # JSON output for parsing
 - `--parent <id>`: Children of specific entry
 - `--orphans`: Only entries without parent
 - `--since <duration>`: e.g., 7d, 24h, 2w
+- `--due-before <date>`: Due before date (YYYY-MM-DD or 3d/1w)
+- `--due-after <date>`: Due after date (YYYY-MM-DD or 3d/1w)
+- `--overdue`: Only overdue entries
+- `--has-due`: Only entries with due dates
+- `--no-due`: Only entries without due dates
 - `--all`: All statuses except archived
 - `--done`: Include done entries
 - `--archived`: Show only archived
 - `--limit <n>`: Max entries (default: 50)
-- `--sort <field>`: created, updated, priority
+- `--sort <field>`: created, updated, priority, due
 - `--reverse`: Reverse sort order
 - `--json`: JSON output
 
@@ -437,6 +452,7 @@ Critical for preventing accidental mass changes:
   "tags": ["tag1", "tag2"],
   "parent": "parent-id|null",
   "related": ["id1", "id2"],
+  "due": "2026-01-10T23:59:59.000Z",
   "createdAt": "2026-01-05T08:30:00.000Z",
   "updatedAt": "2026-01-05T08:30:00.000Z",
   "source": "cli|agent|import"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synap",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A CLI for externalizing your working memory",
   "main": "src/cli.js",
   "bin": {

package/scripts/postinstall.js

@@ -2,17 +2,9 @@
 
 /**
  * postinstall.js - Run after npm install
- * Shows hints and optionally auto-updates the skill
+ * Auto-installs/updates the Claude skill
  */
 
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const SKILL_NAME = 'synap-assistant';
-const TARGET_SKILL_DIR = path.join(os.homedir(), '.claude', 'skills', SKILL_NAME);
-const TARGET_SKILL_FILE = path.join(TARGET_SKILL_DIR, 'SKILL.md');
-
 // ANSI colors
 const CYAN = '\x1b[36m';
 const RESET = '\x1b[0m';
@@ -23,24 +15,19 @@ async function main() {
   console.log(`${BOLD}synap${RESET} - A CLI for externalizing your working memory`);
   console.log('');
 
-  // Check if skill is installed
-  if (fs.existsSync(TARGET_SKILL_FILE)) {
-    try {
-      const skillInstaller = require('../src/skill-installer');
-      const result = await skillInstaller.install();
-      if (result.installed) {
-        console.log(`${CYAN}Skill auto-updated.${RESET}`);
-      } else if (result.skipped) {
-        console.log(`${CYAN}Skill already up to date.${RESET}`);
-      } else if (result.needsForce) {
-        console.log(`${CYAN}Skill modified locally.${RESET} Run 'synap install-skill --force' to update.`);
-      }
-    } catch (err) {
-      console.log(`${CYAN}Skill update failed.${RESET} Run 'synap install-skill' to retry.`);
+  // Auto-install/update skill
+  try {
+    const skillInstaller = require('../src/skill-installer');
+    const result = await skillInstaller.install();
+    if (result.installed) {
+      console.log(`${CYAN}Claude skill installed.${RESET}`);
+    } else if (result.skipped) {
+      console.log(`${CYAN}Claude skill up to date.${RESET}`);
+    } else if (result.needsForce) {
+      console.log(`${CYAN}Skill modified locally.${RESET} Run 'synap install-skill --force' to update.`);
     }
-  } else {
-    console.log('To enable AI agent integration, run:');
-    console.log(`  ${CYAN}synap install-skill${RESET}`);
+  } catch (err) {
+    console.log(`${CYAN}Skill install failed.${RESET} Run 'synap install-skill' to retry.`);
   }
 
   console.log('');

package/src/cli.js

@@ -63,6 +63,24 @@ async function main() {
     return date.toLocaleString();
   };
 
+  // Helper: Format due date for display
+  const formatDueDate = (dateStr) => {
+    const date = new Date(dateStr);
+    if (isNaN(date.getTime())) return 'invalid date';
+
+    const now = new Date();
+    const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const startOfDue = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+    const diffDays = Math.round((startOfDue - startOfToday) / (24 * 60 * 60 * 1000));
+
+    if (diffDays === 0) return 'today';
+    if (diffDays === 1) return 'tomorrow';
+    if (diffDays === -1) return 'yesterday';
+    if (diffDays > 1 && diffDays <= 7) return `in ${diffDays} days`;
+    if (diffDays < -1 && diffDays >= -7) return `${Math.abs(diffDays)} days ago`;
+    return date.toLocaleDateString();
+  };
+
   // ============================================
   // CAPTURE COMMANDS
   // ============================================
@@ -75,27 +93,39 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(async (contentParts, options) => {
       const content = contentParts.join(' ');
       const tags = mergeTags(options.tags);
 
-      const entry = await storage.addEntry({
-        content,
-        title: options.title,
-        type: options.type,
-        priority: options.priority ? parseInt(options.priority, 10) : undefined,
-        tags,
-        parent: options.parent,
-        source: 'cli'
-      });
+      try {
+        const entry = await storage.addEntry({
+          content,
+          title: options.title,
+          type: options.type,
+          priority: options.priority ? parseInt(options.priority, 10) : undefined,
+          tags,
+          parent: options.parent,
+          due: options.due,
+          source: 'cli'
+        });
 
-      if (options.json) {
-        console.log(JSON.stringify({ success: true, entry }, null, 2));
-      } else {
-        const shortId = entry.id.slice(0, 8);
-        const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
-        console.log(chalk.green(`Added ${entry.type} ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"`);
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, entry }, null, 2));
+        } else {
+          const shortId = entry.id.slice(0, 8);
+          const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
+          const dueBadge = entry.due ? chalk.magenta(` [due: ${formatDueDate(entry.due)}]`) : '';
+          console.log(chalk.green(`Added ${entry.type} ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"` + dueBadge);
+        }
+      } catch (err) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: err.message, code: 'INVALID_DUE_DATE' }));
+        } else {
+          console.error(chalk.red(err.message));
+        }
+        process.exit(1);
       }
     });
 
@@ -105,26 +135,38 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(async (contentParts, options) => {
       const content = contentParts.join(' ');
       const tags = mergeTags(options.tags);
 
-      const entry = await storage.addEntry({
-        content,
-        type: 'todo',
-        priority: options.priority ? parseInt(options.priority, 10) : undefined,
-        tags,
-        parent: options.parent,
-        source: 'cli'
-      });
+      try {
+        const entry = await storage.addEntry({
+          content,
+          type: 'todo',
+          priority: options.priority ? parseInt(options.priority, 10) : undefined,
+          tags,
+          parent: options.parent,
+          due: options.due,
+          source: 'cli'
+        });
 
-      if (options.json) {
-        console.log(JSON.stringify({ success: true, entry }, null, 2));
-      } else {
-        const shortId = entry.id.slice(0, 8);
-        const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
-        console.log(chalk.green(`Added todo ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"`);
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, entry }, null, 2));
+        } else {
+          const shortId = entry.id.slice(0, 8);
+          const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
+          const dueBadge = entry.due ? chalk.magenta(` [due: ${formatDueDate(entry.due)}]`) : '';
+          console.log(chalk.green(`Added todo ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"` + dueBadge);
+        }
+      } catch (err) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: err.message, code: 'INVALID_DUE_DATE' }));
+        } else {
+          console.error(chalk.red(err.message));
+        }
+        process.exit(1);
       }
     });
 
@@ -134,26 +176,38 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(async (contentParts, options) => {
       const content = contentParts.join(' ');
       const tags = mergeTags(options.tags);
 
-      const entry = await storage.addEntry({
-        content,
-        type: 'question',
-        priority: options.priority ? parseInt(options.priority, 10) : undefined,
-        tags,
-        parent: options.parent,
-        source: 'cli'
-      });
+      try {
+        const entry = await storage.addEntry({
+          content,
+          type: 'question',
+          priority: options.priority ? parseInt(options.priority, 10) : undefined,
+          tags,
+          parent: options.parent,
+          due: options.due,
+          source: 'cli'
+        });
 
-      if (options.json) {
-        console.log(JSON.stringify({ success: true, entry }, null, 2));
-      } else {
-        const shortId = entry.id.slice(0, 8);
-        const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
-        console.log(chalk.green(`Added question ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"`);
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, entry }, null, 2));
+        } else {
+          const shortId = entry.id.slice(0, 8);
+          const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
+          const dueBadge = entry.due ? chalk.magenta(` [due: ${formatDueDate(entry.due)}]`) : '';
+          console.log(chalk.green(`Added question ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"` + dueBadge);
+        }
+      } catch (err) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: err.message, code: 'INVALID_DUE_DATE' }));
+        } else {
+          console.error(chalk.red(err.message));
+        }
+        process.exit(1);
       }
     });
 
@@ -163,21 +217,32 @@ async function main() {
       const content = contentParts.join(' ');
       const tags = mergeTags(options.tags);
 
-      const entry = await storage.addEntry({
-        content,
-        type: typeName,
-        priority: options.priority ? parseInt(options.priority, 10) : undefined,
-        tags,
-        parent: options.parent,
-        source: 'cli'
-      });
+      try {
+        const entry = await storage.addEntry({
+          content,
+          type: typeName,
+          priority: options.priority ? parseInt(options.priority, 10) : undefined,
+          tags,
+          parent: options.parent,
+          due: options.due,
+          source: 'cli'
+        });
 
-      if (options.json) {
-        console.log(JSON.stringify({ success: true, entry }, null, 2));
-      } else {
-        const shortId = entry.id.slice(0, 8);
-        const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
-        console.log(chalk.green(`Added ${displayName} ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"`);
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, entry }, null, 2));
+        } else {
+          const shortId = entry.id.slice(0, 8);
+          const priorityBadge = entry.priority ? chalk.yellow(`[P${entry.priority}] `) : '';
+          const dueBadge = entry.due ? chalk.magenta(` [due: ${formatDueDate(entry.due)}]`) : '';
+          console.log(chalk.green(`Added ${displayName} ${shortId}: `) + priorityBadge + `"${content.slice(0, 50)}${content.length > 50 ? '...' : ''}"` + dueBadge);
+        }
+      } catch (err) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: err.message, code: 'INVALID_DUE_DATE' }));
+        } else {
+          console.error(chalk.red(err.message));
+        }
+        process.exit(1);
       }
     };
   };
@@ -188,6 +253,7 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('idea'));
 
@@ -197,6 +263,7 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('project'));
 
@@ -206,6 +273,7 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('feature'));
 
@@ -215,6 +283,7 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('note'));
 
@@ -224,6 +293,7 @@ async function main() {
     .option('-p, --priority <priority>', 'Priority level (1=high, 2=medium, 3=low)')
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--parent <id>', 'Parent entry ID')
+    .option('--due <date>', 'Due date (YYYY-MM-DD, 3d/1w, or keywords: today, tomorrow, next monday)')
     .option('--json', 'Output as JSON')
     .action(createTypeShorthand('reference', 'reference'));
 
@@ -246,11 +316,16 @@ async function main() {
     .option('--since <duration>', 'Created after (e.g., 7d, 24h)')
     .option('--before <duration>', 'Created before (e.g., 7d, 24h)')
     .option('--between <range>', 'Date range: start,end (e.g., 2025-01-01,2025-01-31)')
+    .option('--due-before <date>', 'Due before date (YYYY-MM-DD or 3d/1w)')
+    .option('--due-after <date>', 'Due after date (YYYY-MM-DD or 3d/1w)')
+    .option('--overdue', 'Only overdue entries')
+    .option('--has-due', 'Only entries with due dates')
+    .option('--no-due', 'Only entries without due dates')
     .option('-a, --all', 'Include all statuses except archived')
     .option('--done', 'Include done entries')
     .option('--archived', 'Show only archived entries')
     .option('-n, --limit <n>', 'Max entries to return', '50')
-    .option('--sort <field>', 'Sort by: created, updated, priority', 'created')
+    .option('--sort <field>', 'Sort by: created, updated, priority, due', 'created')
     .option('--reverse', 'Reverse sort order')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
@@ -271,6 +346,10 @@ async function main() {
           const [start, end] = options.between.split(',');
           return { start: start.trim(), end: end.trim() };
         })() : undefined,
+        dueBefore: options.dueBefore,
+        dueAfter: options.dueAfter,
+        overdue: options.overdue,
+        hasDue: options.hasDue ? true : (options.due === false ? false : undefined),
         includeDone: options.done || options.all,
         limit: parseInt(options.limit, 10),
         sort: options.sort,
@@ -314,7 +393,13 @@ async function main() {
             const title = entry.title || entry.content.slice(0, 40);
             const truncated = title.length > 40 ? '...' : '';
             const timeStr = chalk.gray(formatTime(entry.createdAt));
-            console.log(`  ${chalk.blue(shortId)}  ${priorityBadge} ${title}${truncated}${tags} ${timeStr}`);
+            let dueStr = '';
+            if (entry.due) {
+              const isOverdue = new Date(entry.due) < new Date() && entry.status !== 'done';
+              const dueText = formatDueDate(entry.due);
+              dueStr = isOverdue ? chalk.red(` [OVERDUE: ${dueText}]`) : chalk.magenta(` [due: ${dueText}]`);
+            }
+            console.log(`  ${chalk.blue(shortId)}  ${priorityBadge} ${title}${truncated}${tags}${dueStr} ${timeStr}`);
           }
           console.log('');
         }
@@ -374,6 +459,12 @@ async function main() {
 
         console.log(`  ${chalk.gray('Created:')}  ${formatTime(entry.createdAt)}`);
         console.log(`  ${chalk.gray('Updated:')}  ${formatTime(entry.updatedAt)}`);
+        if (entry.due) {
+          const isOverdue = new Date(entry.due) < new Date() && entry.status !== 'done';
+          const dueColor = isOverdue ? chalk.red : chalk.magenta;
+          const overdueLabel = isOverdue ? ' (OVERDUE)' : '';
+          console.log(`  ${chalk.gray('Due:')}      ${dueColor(formatDueDate(entry.due))}${overdueLabel}`);
+        }
         if (entry.source) {
           console.log(`  ${chalk.gray('Source:')}   ${entry.source}`);
         }
@@ -517,6 +608,8 @@ async function main() {
     .option('--remove-tags <tags>', 'Remove tags')
     .option('--parent <id>', 'Set parent')
     .option('--clear-parent', 'Remove parent')
+    .option('--due <date>', 'Set due date')
+    .option('--clear-due', 'Remove due date')
     .option('--json', 'Output as JSON')
     .action(async (id, options) => {
       const entry = await storage.getEntry(id);
@@ -546,6 +639,19 @@ async function main() {
       }
       if (options.parent) updates.parent = options.parent;
       if (options.clearParent) updates.parent = null;
+      if (options.due) {
+        const dueDate = storage.parseDate(options.due);
+        if (!dueDate) {
+          if (options.json) {
+            console.log(JSON.stringify({ success: false, error: `Invalid due date: ${options.due}`, code: 'INVALID_DUE_DATE' }));
+          } else {
+            console.error(chalk.red(`Invalid due date: ${options.due}`));
+          }
+          process.exit(1);
+        }
+        updates.due = dueDate;
+      }
+      if (options.clearDue) updates.due = null;
 
       const updated = await storage.updateEntry(entry.id, updates);
 
@@ -1043,7 +1149,7 @@ async function main() {
 
   program
     .command('focus')
-    .description('Show what to work on now: P1 todos + active projects')
+    .description('Show what to work on now: P1 todos + overdue + active projects')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
       // Get P1 todos
@@ -1054,6 +1160,17 @@ async function main() {
         limit: 100
       });
 
+      // Get overdue entries
+      const overdueEntries = await storage.listEntries({
+        overdue: true,
+        status: 'raw,active',
+        limit: 100
+      });
+
+      // Deduplicate (some P1 todos may also be overdue)
+      const p1TodoIds = new Set(p1Todos.entries.map(e => e.id));
+      const overdueNotP1 = overdueEntries.entries.filter(e => !p1TodoIds.has(e.id));
+
       // Get active projects with progress
       const projects = await storage.listEntries({
         type: 'project',
@@ -1075,18 +1192,32 @@ async function main() {
         console.log(JSON.stringify({
           success: true,
           p1Todos: p1Todos.entries,
+          overdueItems: overdueNotP1,
           activeProjects: projectsWithProgress
         }, null, 2));
       } else {
         console.log(chalk.bold('Focus: What to work on now\n'));
 
+        // Overdue section (show first - most urgent)
+        if (overdueNotP1.length > 0) {
+          console.log(chalk.red.bold('Overdue:'));
+          for (const item of overdueNotP1) {
+            const shortId = item.id.slice(0, 8);
+            const title = item.title || item.content.slice(0, 50);
+            const dueStr = formatDueDate(item.due);
+            console.log(`  ${chalk.blue(shortId)} ${title} ${chalk.red(`[${dueStr}]`)}`);
+          }
+          console.log();
+        }
+
         // P1 Todos
         if (p1Todos.entries.length > 0) {
           console.log(chalk.yellow.bold('P1 Todos:'));
           for (const todo of p1Todos.entries) {
             const shortId = todo.id.slice(0, 8);
             const title = todo.title || todo.content.slice(0, 50);
-            console.log(`  ${chalk.blue(shortId)} ${title}`);
+            const dueStr = todo.due ? chalk.magenta(` [due: ${formatDueDate(todo.due)}]`) : '';
+            console.log(`  ${chalk.blue(shortId)} ${title}${dueStr}`);
           }
           console.log();
         } else {

package/src/storage.js

@@ -201,6 +201,89 @@ function parseDuration(duration) {
   return value * multipliers[unit];
 }
 
+/**
+ * Parse date input to ISO string
+ * Supports: ISO dates ("2025-01-15"), relative ("3d", "1w"), natural language ("tomorrow", "next Monday")
+ * @param {string} input - Date input string
+ * @returns {string|null} - ISO date string or null if invalid
+ */
+function parseDate(input) {
+  if (typeof input !== 'string') return null;
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+
+  const lowered = trimmed.toLowerCase();
+  const dayMs = 24 * 60 * 60 * 1000;
+
+  const endOfDay = (date) => {
+    const next = new Date(date);
+    next.setHours(23, 59, 59, 999);
+    return next;
+  };
+
+  if (lowered === 'today') {
+    return endOfDay(new Date()).toISOString();
+  }
+  if (lowered === 'tomorrow') {
+    return endOfDay(new Date(Date.now() + dayMs)).toISOString();
+  }
+  if (lowered === 'yesterday') {
+    return endOfDay(new Date(Date.now() - dayMs)).toISOString();
+  }
+
+  const nextWeekdayMatch = lowered.match(/^next\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)$/);
+  if (nextWeekdayMatch) {
+    const weekdays = {
+      sunday: 0,
+      monday: 1,
+      tuesday: 2,
+      wednesday: 3,
+      thursday: 4,
+      friday: 5,
+      saturday: 6
+    };
+    const target = weekdays[nextWeekdayMatch[1]];
+    const now = new Date();
+    const current = now.getDay();
+    let diff = (target + 7 - current) % 7;
+    if (diff === 0) diff = 7;
+    return endOfDay(new Date(now.getTime() + diff * dayMs)).toISOString();
+  }
+
+  const inMatch = lowered.match(/^in\s+(\d+)\s*(hour|hours|day|days|week|weeks|month|months)$/);
+  if (inMatch) {
+    const value = parseInt(inMatch[1], 10);
+    const unit = inMatch[2];
+    const multipliers = {
+      hour: 60 * 60 * 1000,
+      hours: 60 * 60 * 1000,
+      day: dayMs,
+      days: dayMs,
+      week: 7 * dayMs,
+      weeks: 7 * dayMs,
+      month: 30 * dayMs,
+      months: 30 * dayMs
+    };
+    return new Date(Date.now() + value * multipliers[unit]).toISOString();
+  }
+
+  // Try relative duration first (3d, 1w, etc.) - for FUTURE dates
+  const durationMs = parseDuration(trimmed);
+  if (durationMs !== null) {
+    return new Date(Date.now() + durationMs).toISOString();
+  }
+
+  // Try ISO date (YYYY-MM-DD)
+  if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+    const date = new Date(trimmed + 'T23:59:59');
+    if (!isNaN(date.getTime())) {
+      return date.toISOString();
+    }
+  }
+
+  return null;
+}
+
 /**
  * Add a new entry
  */
@@ -216,6 +299,16 @@ async function addEntry(options) {
     }
   }
 
+  // Parse due date if provided
+  let dueDate = undefined;
+  const dueInput = typeof options.due === 'string' ? options.due.trim() : options.due;
+  if (dueInput) {
+    dueDate = parseDate(dueInput);
+    if (!dueDate) {
+      throw new Error(`Invalid due date: ${options.due}`);
+    }
+  }
+
   const now = new Date().toISOString();
   const entry = {
     id: uuidv4(),
@@ -227,6 +320,7 @@ async function addEntry(options) {
     tags: options.tags || [],
     parent: parentId || undefined,
     related: [],
+    due: dueDate,
     createdAt: now,
     updatedAt: now,
     source: options.source || 'cli'
@@ -392,6 +486,40 @@ async function listEntries(query = {}) {
     });
   }
 
+  // Filter by due before
+  if (query.dueBefore) {
+    const cutoffDate = parseDate(query.dueBefore);
+    if (cutoffDate) {
+      entries = entries.filter(e => e.due && new Date(e.due) <= new Date(cutoffDate));
+    }
+  }
+
+  // Filter by due after
+  if (query.dueAfter) {
+    const cutoffDate = parseDate(query.dueAfter);
+    if (cutoffDate) {
+      entries = entries.filter(e => e.due && new Date(e.due) >= new Date(cutoffDate));
+    }
+  }
+
+  // Filter overdue (due before now, not done/archived)
+  if (query.overdue) {
+    const now = new Date();
+    entries = entries.filter(e =>
+      e.due &&
+      new Date(e.due) < now &&
+      e.status !== 'done' &&
+      e.status !== 'archived'
+    );
+  }
+
+  // Filter entries with/without due date
+  if (query.hasDue === true) {
+    entries = entries.filter(e => e.due);
+  } else if (query.hasDue === false) {
+    entries = entries.filter(e => !e.due);
+  }
+
   // Include done if requested
   if (!query.includeDone && query.status !== 'done') {
     entries = entries.filter(e => e.status !== 'done');
@@ -400,6 +528,13 @@ async function listEntries(query = {}) {
   // Sort
   const sortField = query.sort || 'created';
   entries.sort((a, b) => {
+    if (sortField === 'due') {
+      // Entries without due dates go to the end
+      if (!a.due && !b.due) return 0;
+      if (!a.due) return 1;
+      if (!b.due) return -1;
+      return new Date(a.due) - new Date(b.due);
+    }
     if (sortField === 'priority') {
       const pA = a.priority || 99;
       const pB = b.priority || 99;
@@ -518,6 +653,7 @@ async function updateEntry(id, updates) {
   // Handle null values (clear fields)
   if (updates.priority === null) delete entry.priority;
   if (updates.parent === null) delete entry.parent;
+  if (updates.due === null) delete entry.due;
 
   saveEntries(data);
 
@@ -794,6 +930,7 @@ module.exports = {
   getDefaultConfig,
   validateConfigValue,
   saveConfig,
+  parseDate,
   CONFIG_DIR,
   ENTRIES_FILE,
   ARCHIVE_FILE,