@masslessai/push-todo 3.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "push-todo",
+  "version": "3.0.0",
+  "description": "Voice tasks from Push iOS app"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MasslessAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @masslessai/push-todo
+
+Voice tasks from the [Push iOS app](https://pushto.do) for Claude Code.
+
+## Installation
+
+```bash
+npm install -g @masslessai/push-todo
+```
+
+## Quick Start
+
+```bash
+# Authenticate and set up
+push-todo connect
+
+# List your tasks
+push-todo
+
+# Work on a specific task
+push-todo 427
+```
+
+## Features
+
+- **Voice Tasks**: Tasks captured by voice on your iPhone sync to your terminal
+- **Project Filtering**: Automatically shows tasks relevant to your current git repo
+- **E2EE Support**: End-to-end encrypted tasks are decrypted using your iCloud Keychain
+- **Claude Code Integration**: Works as a Claude Code plugin with `/push-todo` command
+- **Daemon Execution**: Background task execution with progress monitoring
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `push-todo` | List active tasks |
+| `push-todo <number>` | View specific task |
+| `push-todo connect` | Authenticate and set up |
+| `push-todo search <query>` | Search tasks |
+| `push-todo status` | Show connection status |
+| `push-todo --watch` | Live monitoring UI |
+
+## Claude Code Integration
+
+This package works as a Claude Code plugin:
+
+```
+/push-todo              List your voice tasks
+/push-todo 427          Work on task #427
+/push-todo connect      Run diagnostics
+```
+
+### Session Hooks
+
+- **Session Start**: Shows task count notification
+- **Session End**: Reports session completion
+
+## Options
+
+```bash
+push-todo --all-projects     # Tasks from all projects
+push-todo --backlog          # Show backlog items
+push-todo --include-backlog  # Include backlog in list
+push-todo --completed        # Show completed items
+push-todo --json             # Output as JSON
+push-todo --queue 1,2,3      # Queue tasks for daemon
+```
+
+## Configuration
+
+Config stored at `~/.config/push/config`:
+
+```bash
+push-todo setting            # Show all settings
+push-todo setting auto-commit # Toggle auto-commit
+```
+
+## Requirements
+
+- Node.js 18+
+- macOS (for E2EE features)
+- [Push iOS app](https://apps.apple.com/app/push-todo/id6738972839)
+
+## API
+
+```javascript
+import { listTasks, showTask, searchTasks } from '@masslessai/push-todo';
+
+// List tasks
+const tasks = await listTasks({ allProjects: true });
+
+// Get specific task
+const task = await showTask(427);
+
+// Search
+const results = await searchTasks('bug');
+```
+
+## Documentation
+
+- [Skill Documentation](./SKILL.md)
+- [Push Website](https://pushto.do)
+- [Support](mailto:support@pushto.do)
+
+## License
+
+MIT © [MasslessAI](https://masslessai.com)

package/SKILL.md

@@ -0,0 +1,180 @@
+# Push Todo Skill
+
+This skill enables Claude Code to fetch and work on voice tasks captured via the Push iOS app.
+
+## Quick Start
+
+1. Run `push-todo connect` to authenticate
+2. Run `push-todo` to list active tasks
+3. Run `push-todo <number>` to view and work on a specific task
+
+## Commands
+
+### List Tasks
+
+```bash
+push-todo                    # Active tasks for current project
+push-todo --all-projects     # Tasks from all projects
+push-todo --backlog          # Backlog items only
+push-todo --include-backlog  # Active + backlog
+push-todo --completed        # Completed items only
+push-todo --json             # Output as JSON
+```
+
+### View Specific Task
+
+```bash
+push-todo 427                # View task #427
+push-todo 427 --json         # As JSON
+```
+
+### Search Tasks
+
+```bash
+push-todo search "auth bug"  # Search for tasks
+push-todo --search "fix"     # Alternative syntax
+```
+
+### Manage Tasks
+
+```bash
+push-todo --queue 427,428    # Queue tasks for daemon
+push-todo --queue-batch      # Auto-queue a batch
+push-todo --mark-completed <uuid> --completion-comment "Fixed the bug"
+```
+
+### Connection & Status
+
+```bash
+push-todo connect            # Run diagnostics, authenticate
+push-todo status             # Show connection status
+push-todo setting            # Show all settings
+push-todo setting auto-commit # Toggle a setting
+```
+
+### Monitor
+
+```bash
+push-todo --watch            # Live terminal UI
+push-todo --watch --json     # JSON status output
+```
+
+## Task Format
+
+Tasks include:
+
+- **summary**: Brief title
+- **content/normalizedContent**: Full task description (AI-extracted)
+- **originalTranscript**: Raw voice recording text
+- **displayNumber**: Human-readable number (#1, #2...)
+- **projectHint**: Associated project (git remote)
+- **screenshotAttachments**: Any attached screenshots
+- **linkAttachments**: Any attached links
+
+## Batch Processing
+
+The CLI supports batch task processing:
+
+1. Fetch multiple tasks with `push-todo`
+2. Tasks marked for batch will show `BATCH_OFFER` format
+3. Use `--queue` to add tasks to the daemon queue
+
+## Integration with Claude Code
+
+### Session Start Hook
+
+When Claude Code starts, the hook shows:
+```
+[Push] You have 5 active tasks from your iPhone. Say 'push-todo' to see them.
+```
+
+### Session End Hook
+
+Reports session completion to the Push backend.
+
+### Slash Command
+
+Use `/push-todo` in Claude Code as a shortcut:
+- `/push-todo` - List tasks
+- `/push-todo 427` - Work on task #427
+- `/push-todo connect` - Run diagnostics
+
+## Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `AUTO_COMMIT` | `true` | Auto-commit changes after task completion |
+| `MAX_BATCH_SIZE` | `5` | Maximum tasks in batch offer |
+
+Toggle with: `push-todo setting auto-commit`
+
+## Project Registration
+
+Projects are identified by their git remote URL. Register with:
+
+```bash
+push-todo connect
+```
+
+This maps the git remote to the local path, enabling:
+- Automatic project filtering
+- Daemon task routing
+- Cross-machine synchronization
+
+## E2EE (End-to-End Encryption)
+
+If enabled on the Push app:
+- Tasks are encrypted on device
+- Decryption uses iCloud Keychain
+- Requires macOS with keychain access
+
+Check status: `push-todo status`
+
+## Configuration
+
+Config file: `~/.config/push/config`
+
+```bash
+export PUSH_KEY="your-api-key"
+export PUSH_USER_ID="user-uuid"
+export AUTO_COMMIT="true"
+export MAX_BATCH_SIZE="5"
+```
+
+## Troubleshooting
+
+### "No API key configured"
+Run `push-todo connect` to authenticate.
+
+### "E2EE not available"
+The keychain helper binary may not be installed. Check:
+- macOS only (not Linux/Windows)
+- Binary at `node_modules/@masslessai/push-todo/bin/push-keychain-helper`
+
+### "Invalid API key"
+Your key may have expired. Run `push-todo connect` to re-authenticate.
+
+### Tasks not showing for project
+Run `push-todo connect` to register the current project, or use `--all-projects`.
+
+## API Reference
+
+The CLI also exports a programmatic API:
+
+```javascript
+import {
+  listTasks,
+  showTask,
+  searchTasks,
+  markComplete
+} from '@masslessai/push-todo';
+
+// List tasks
+const tasks = await listTasks({ allProjects: true });
+
+// Search
+const results = await searchTasks('bug fix');
+
+// Mark complete
+await markComplete(taskId, 'Fixed the issue');
+```

package/bin/push-todo.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * Push Todo CLI
+ *
+ * Voice tasks from Push iOS app for Claude Code.
+ * This is the main CLI entry point.
+ *
+ * Usage:
+ *   push-todo              # List active tasks
+ *   push-todo 427          # Get specific task
+ *   push-todo connect      # Setup connection
+ *   push-todo status       # Show status
+ *   push-todo watch        # Live daemon monitor
+ */
+
+import { run } from '../lib/cli.js';
+
+// Run CLI with arguments
+run(process.argv.slice(2)).catch(error => {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+});

package/commands/push-todo.md

@@ -0,0 +1,78 @@
+# Push Todo - Voice Tasks from iPhone
+
+Fetch and work on voice tasks captured via the Push iOS app.
+
+## How to Use
+
+Run `/push-todo` to see your active tasks, or `/push-todo <number>` to work on a specific task.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/push-todo` | List all active tasks for current project |
+| `/push-todo <number>` | Work on specific task (e.g., `/push-todo 427`) |
+| `/push-todo --all-projects` | List tasks from all projects |
+| `/push-todo --backlog` | Show backlog items |
+| `/push-todo connect` | Run connection diagnostics |
+| `/push-todo search <query>` | Search tasks |
+| `/push-todo status` | Show connection status |
+
+## Task Output Format
+
+When you fetch a task, you'll see:
+
+```
+## Task: #427 Fix authentication bug
+
+**Project:** github.com/user/repo
+
+### Content
+Users are getting logged out randomly. Need to investigate the session token expiration logic.
+
+### Original Voice Transcript
+> "There's a bug where users get logged out randomly, I think it's the session token expiration"
+
+**Task ID:** `550e8400-e29b-41d4-a716-446655440000`
+**Display Number:** #427
+**Status:** Active
+**Created:** 2026-01-15T10:30:00Z
+```
+
+## Batch Offer Format
+
+When multiple tasks are available, you may see a batch offer:
+
+```
+==================================================
+BATCH_OFFER: 3
+BATCH_TASKS: 427,428,429
+  #427 - Fix authentication bug
+  #428 - Add dark mode support
+  #429 - Update API documentation
+==================================================
+```
+
+## Working on Tasks
+
+When you fetch a specific task:
+
+1. Read the **Content** section for the full task description
+2. Check the **Original Voice Transcript** for additional context
+3. Implement the requested changes
+4. Mark the task as completed when done
+
+## Completion
+
+After completing a task, the task will be marked as done and synced back to the Push app on your iPhone.
+
+## Project Context
+
+Tasks are associated with git repositories. The CLI automatically detects your current project and shows only relevant tasks.
+
+- Use `--all-projects` to see tasks from all registered projects
+- Run `push-todo connect` to register the current project
+
+## E2EE Support
+
+If you have End-to-End Encryption enabled on the Push app, the CLI will automatically decrypt task content using your iCloud Keychain.

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-end.js",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-end.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * Session end hook for Push CLI.
+ *
+ * Reports session completion status to the backend.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CONFIG_FILE = join(homedir(), '.config', 'push', 'config');
+const API_BASE = 'https://jxuzqcbqhiaxmfitzxlo.supabase.co/functions/v1';
+
+/**
+ * Get the API key from config.
+ */
+function getApiKey() {
+  if (process.env.PUSH_API_KEY) {
+    return process.env.PUSH_API_KEY;
+  }
+
+  if (!existsSync(CONFIG_FILE)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(CONFIG_FILE, 'utf8');
+    const match = content.match(/^export\s+PUSH_KEY\s*=\s*["']?([^"'\n]+)["']?/m);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the machine ID.
+ */
+function getMachineId() {
+  const machineIdFile = join(homedir(), '.config', 'push', 'machine_id');
+
+  if (existsSync(machineIdFile)) {
+    try {
+      return readFileSync(machineIdFile, 'utf8').trim();
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Report session end to backend.
+ */
+async function reportSessionEnd(apiKey, machineId, exitReason) {
+  try {
+    const response = await fetch(`${API_BASE}/session-end`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        machine_id: machineId,
+        exit_reason: exitReason,
+        timestamp: new Date().toISOString()
+      }),
+      signal: AbortSignal.timeout(10000)
+    });
+
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+  const apiKey = getApiKey();
+  const machineId = getMachineId();
+
+  if (!apiKey || !machineId) {
+    // Not configured - silent exit
+    process.exit(0);
+  }
+
+  // Get exit reason from environment (Claude Code may set this)
+  const exitReason = process.env.CLAUDE_EXIT_REASON || 'normal';
+
+  // Report to backend
+  await reportSessionEnd(apiKey, machineId, exitReason);
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/session-start.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * Session start hook for Push CLI.
+ *
+ * Displays task count notification when Claude Code starts.
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CONFIG_FILE = join(homedir(), '.config', 'push', 'config');
+const API_BASE = 'https://jxuzqcbqhiaxmfitzxlo.supabase.co/functions/v1';
+
+/**
+ * Get the API key from config.
+ */
+function getApiKey() {
+  // Check environment variable first
+  if (process.env.PUSH_API_KEY) {
+    return process.env.PUSH_API_KEY;
+  }
+
+  // Read from config file
+  if (!existsSync(CONFIG_FILE)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(CONFIG_FILE, 'utf8');
+    const match = content.match(/^export\s+PUSH_KEY\s*=\s*["']?([^"'\n]+)["']?/m);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the git remote for the current directory.
+ */
+function getGitRemote() {
+  try {
+    const result = execSync('git remote get-url origin', {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let url = result.trim();
+    if (!url) return null;
+
+    // Normalize
+    const prefixes = ['https://', 'http://', 'git@', 'ssh://git@'];
+    for (const prefix of prefixes) {
+      if (url.startsWith(prefix)) {
+        url = url.slice(prefix.length);
+        break;
+      }
+    }
+
+    if (url.includes(':') && !url.includes('://')) {
+      url = url.replace(':', '/');
+    }
+
+    if (url.endsWith('.git')) {
+      url = url.slice(0, -4);
+    }
+
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch task count from the API.
+ */
+async function fetchTaskCount(apiKey, gitRemote) {
+  try {
+    const params = new URLSearchParams();
+    if (gitRemote) {
+      params.set('git_remote', gitRemote);
+    }
+    params.set('count_only', 'true');
+
+    const url = `${API_BASE}/synced-todos?${params}`;
+    const response = await fetch(url, {
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      signal: AbortSignal.timeout(5000)
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const data = await response.json();
+    return data.count || 0;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+  const apiKey = getApiKey();
+
+  if (!apiKey) {
+    // No API key - silent exit
+    process.exit(0);
+  }
+
+  const gitRemote = getGitRemote();
+  const count = await fetchTaskCount(apiKey, gitRemote);
+
+  if (count === null) {
+    // API error - silent exit
+    process.exit(0);
+  }
+
+  if (count > 0) {
+    // Output notification for Claude Code
+    console.log(`[Push] You have ${count} active task${count !== 1 ? 's' : ''} from your iPhone. Say 'push-todo' to see them.`);
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));