@gracefultools/astrid-sdk 0.4.1 → 0.6.0

package/dist/bin/cli.js

@@ -6,7 +6,8 @@
  * Command-line interface for running the Astrid AI agent worker
  *
  * Usage:
- *   npx astrid-agent                 # Start polling for tasks
+ *   npx astrid-agent                 # Start polling for tasks (API mode)
+ *   npx astrid-agent --terminal      # Start polling using local Claude Code CLI
  *   npx astrid-agent <taskId>        # Process a specific task
  *   npx astrid-agent --help          # Show help
  */
@@ -50,6 +51,7 @@ const path = __importStar(require("path"));
 dotenv.config({ path: path.resolve(process.cwd(), '.env.local') });
 dotenv.config({ path: path.resolve(process.cwd(), '.env') });
 const claude_js_1 = require("../executors/claude.js");
+const terminal_claude_js_1 = require("../executors/terminal-claude.js");
 const openai_js_1 = require("../executors/openai.js");
 const gemini_js_1 = require("../executors/gemini.js");
 const agent_config_js_1 = require("../utils/agent-config.js");
@@ -73,6 +75,11 @@ const CONFIG = {
     vercelToken: process.env.VERCEL_TOKEN,
     // iOS TestFlight
     testflightPublicLink: process.env.TESTFLIGHT_PUBLIC_LINK,
+    // Terminal mode settings
+    terminalMode: process.env.ASTRID_TERMINAL_MODE === 'true',
+    claudeModel: process.env.CLAUDE_MODEL || 'opus',
+    claudeMaxTurns: parseInt(process.env.CLAUDE_MAX_TURNS || '50', 10),
+    defaultProjectPath: process.env.DEFAULT_PROJECT_PATH || process.cwd(),
 };
 function getApiKeyForService(service) {
     switch (service) {
@@ -180,6 +187,76 @@ async function processTask(task, repoPath) {
         }
     }
 }
+/**
+ * Process a task using the local Claude Code CLI (terminal mode)
+ */
+async function processTaskTerminal(task, projectPath, comments, isFollowUp) {
+    const executor = new terminal_claude_js_1.TerminalClaudeExecutor({
+        model: CONFIG.claudeModel,
+        maxTurns: CONFIG.claudeMaxTurns,
+    });
+    // Check if Claude Code CLI is available
+    const isAvailable = await executor.checkAvailable();
+    if (!isAvailable) {
+        return {
+            success: false,
+            error: 'Claude Code CLI not found. Install it with: npm install -g @anthropic-ai/claude-code'
+        };
+    }
+    console.log(`\n🖥️  Terminal Mode: Processing task with local Claude Code CLI`);
+    console.log(`   Task: ${task.title}`);
+    console.log(`   Project: ${projectPath}`);
+    console.log(`   Model: ${CONFIG.claudeModel}`);
+    console.log(`   Max turns: ${CONFIG.claudeMaxTurns}`);
+    // Create session object
+    const session = {
+        id: task.id,
+        taskId: task.id,
+        title: task.title,
+        description: task.description || '',
+        projectPath,
+        provider: 'claude',
+        claudeSessionId: undefined,
+        status: 'pending',
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        messageCount: 0,
+    };
+    const context = { comments };
+    let result;
+    // Check if we should resume an existing session
+    const existingSessionId = await terminal_claude_js_1.terminalSessionStore.getClaudeSessionId(task.id);
+    if (isFollowUp && existingSessionId) {
+        // Get the last user comment as the follow-up input
+        const lastUserComment = comments?.filter(c => !c.authorName.includes('Agent'))?.pop();
+        const input = lastUserComment?.content || 'Please continue with the task.';
+        console.log(`\n🔄 Resuming existing session: ${existingSessionId}`);
+        result = await executor.resumeSession(session, input, context, (msg) => {
+            console.log(`  → ${msg}`);
+        });
+    }
+    else {
+        console.log(`\n🚀 Starting new Claude Code session...`);
+        result = await executor.startSession(session, undefined, context, (msg) => {
+            console.log(`  → ${msg}`);
+        });
+    }
+    // Parse the output
+    const parsed = executor.parseOutput(result.stdout);
+    if (result.exitCode !== 0 && result.exitCode !== null) {
+        return {
+            success: false,
+            error: parsed.error || `Claude Code exited with code ${result.exitCode}`,
+            files: result.modifiedFiles,
+        };
+    }
+    return {
+        success: true,
+        prUrl: result.prUrl || parsed.prUrl,
+        files: result.modifiedFiles || parsed.files,
+        summary: parsed.summary,
+    };
+}
 function isStartingMarker(content) {
     const lower = content.toLowerCase();
     return content.includes('**Starting work**') ||
@@ -234,9 +311,34 @@ function isTerminalState(content) {
 }
 function isRetryComment(content) {
     const lower = content.toLowerCase().trim();
-    return lower === 'retry' ||
-        lower.startsWith('retry ') ||
-        lower.includes('please reprocess');
+    // Match various ways users might ask for retry
+    const retryPhrases = [
+        'retry',
+        'try again',
+        'tryagain',
+        'please retry',
+        'retry please',
+        'reprocess',
+        'please reprocess',
+        'redo',
+        'do again',
+        'run again',
+        'try it again',
+        'give it another try',
+        'one more time',
+        'again please',
+        'again',
+    ];
+    for (const phrase of retryPhrases) {
+        if (lower === phrase || lower.startsWith(phrase + ' ') || lower.endsWith(' ' + phrase)) {
+            return true;
+        }
+    }
+    // Also match if "retry" or "try again" appears anywhere in a short message
+    if (lower.length < 50 && (lower.includes('retry') || lower.includes('try again'))) {
+        return true;
+    }
+    return false;
 }
 function isShipItComment(content) {
     const lower = content.toLowerCase().trim();
@@ -335,7 +437,7 @@ function shouldProcessTask(comments) {
             if (mostRecentUserComment && isRetryComment(mostRecentUserComment.content)) {
                 return { shouldProcess: true, reason: 'User requested retry after failure' };
             }
-            return { shouldProcess: false, reason: 'Task failed - comment "retry" to try again' };
+            return { shouldProcess: false, reason: 'Task failed - comment "retry" or "try again" to retry' };
         }
         // Other completion - don't reprocess unless explicit retry
         if (mostRecentUserComment && isRetryComment(mostRecentUserComment.content)) {
@@ -696,7 +798,207 @@ async function runWorker() {
                             // Post error comment (agentUserId may be undefined if error occurred before lookup)
                             await client.addComment(task.id, `❌ **Processing Failed**\n\n` +
                                 `Error: ${error instanceof Error ? error.message : String(error)}\n\n` +
-                                `Please check the configuration and try again.`, agentUserId || undefined).catch(() => { });
+                                `---\n` +
+                                `💡 **To try again:** Comment "retry" or "try again"\n` +
+                                `💡 **To ship existing PR:** Comment "ship it"`, agentUserId || undefined).catch(() => { });
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.error('❌ Poll error:', error);
+        }
+        // Wait before next poll
+        await new Promise(resolve => setTimeout(resolve, CONFIG.pollIntervalMs));
+    }
+}
+// ============================================================================
+// TERMINAL MODE WORKER LOOP
+// ============================================================================
+/**
+ * Terminal mode worker loop - uses local Claude Code CLI instead of API
+ */
+async function runWorkerTerminal() {
+    const client = new astrid_oauth_js_1.AstridOAuthClient();
+    if (!client.isConfigured()) {
+        console.error('❌ OAuth credentials not configured');
+        console.error('   Set ASTRID_OAUTH_CLIENT_ID and ASTRID_OAUTH_CLIENT_SECRET');
+        process.exit(1);
+    }
+    const listId = CONFIG.astridListId;
+    if (!listId) {
+        console.error('❌ ASTRID_OAUTH_LIST_ID not configured');
+        process.exit(1);
+    }
+    // Check Claude Code CLI availability
+    const executor = new terminal_claude_js_1.TerminalClaudeExecutor({
+        model: CONFIG.claudeModel,
+        maxTurns: CONFIG.claudeMaxTurns,
+    });
+    const isAvailable = await executor.checkAvailable();
+    if (!isAvailable) {
+        console.error('❌ Claude Code CLI not found');
+        console.error('   Install it with: npm install -g @anthropic-ai/claude-code');
+        console.error('   Or use API mode: npx astrid-agent (without --terminal)');
+        process.exit(1);
+    }
+    console.log('🤖 Astrid Agent Worker (Terminal Mode)');
+    console.log(`   List ID: ${listId}`);
+    console.log(`   Poll interval: ${CONFIG.pollIntervalMs}ms`);
+    console.log(`   Project path: ${CONFIG.defaultProjectPath}`);
+    console.log(`   Model: ${CONFIG.claudeModel}`);
+    console.log('');
+    // Test connection
+    const testResult = await client.testConnection();
+    if (!testResult.success) {
+        console.error(`❌ Connection failed: ${testResult.error}`);
+        process.exit(1);
+    }
+    console.log('✅ Connected to Astrid API');
+    console.log('✅ Claude Code CLI available\n');
+    // Polling loop
+    while (true) {
+        try {
+            const tasksResult = await client.getTasks(listId, false);
+            if (tasksResult.success && tasksResult.data) {
+                // Filter for incomplete tasks assigned to AI agents
+                const eligibleTasks = tasksResult.data.filter(task => {
+                    if (task.completed)
+                        return false;
+                    const email = getAssigneeEmail(task);
+                    if (!email || !(0, agent_config_js_1.isRegisteredAgent)(email))
+                        return false;
+                    return true;
+                });
+                if (eligibleTasks.length > 0) {
+                    console.log(`\n📋 Found ${eligibleTasks.length} eligible task(s)`);
+                    for (const task of eligibleTasks) {
+                        // Skip if already being processed
+                        if (processingTasks.has(task.id)) {
+                            console.log(`   ⏳ ${task.id.slice(0, 8)}... already in progress`);
+                            continue;
+                        }
+                        let agentUserId = null;
+                        try {
+                            // Check comments for processing state
+                            const commentsResult = await client.getComments(task.id);
+                            const comments = commentsResult.success ? commentsResult.data || [] : [];
+                            const status = shouldProcessTask(comments);
+                            const assigneeEmail = getAssigneeEmail(task) || 'claude@astrid.cc';
+                            console.log(`\n🔍 Task: ${task.title.slice(0, 50)}...`);
+                            console.log(`   ID: ${task.id}`);
+                            console.log(`   Agent: ${assigneeEmail}`);
+                            console.log(`   Status: ${status.reason}`);
+                            if (!status.shouldProcess) {
+                                continue;
+                            }
+                            const service = (0, agent_config_js_1.getAgentService)(assigneeEmail);
+                            const agentName = `${service.charAt(0).toUpperCase() + service.slice(1)} AI Agent (Terminal)`;
+                            // Get agent user ID
+                            agentUserId = await client.getAgentIdByEmail(assigneeEmail);
+                            if (agentUserId) {
+                                console.log(`   Posting as: ${assigneeEmail} (${agentUserId})`);
+                            }
+                            // Handle "ship it" action
+                            if (status.action === 'ship_it' && status.prUrl) {
+                                console.log(`\n🚀 Ship It! Merging PR: ${status.prUrl}`);
+                                processingTasks.add(task.id);
+                                try {
+                                    const prMatch = status.prUrl.match(/\/pull\/(\d+)/);
+                                    if (!prMatch) {
+                                        throw new Error('Could not extract PR number from URL');
+                                    }
+                                    const prNumber = prMatch[1];
+                                    // Get repo from list
+                                    const listResult = await client.getList(listId);
+                                    const repoString = listResult.data?.githubRepositoryId || listResult.data?.repository;
+                                    if (!repoString) {
+                                        throw new Error('No repository configured for this list');
+                                    }
+                                    const { execSync } = await import('child_process');
+                                    execSync(`gh pr merge ${prNumber} --merge --repo ${repoString}`, { stdio: 'inherit' });
+                                    await client.addComment(task.id, `🎉 **Shipped!**\n\n` +
+                                        `PR #${prNumber} has been merged to main.\n\n` +
+                                        `---\n*Merged by ${agentName}*`, agentUserId || undefined);
+                                    console.log(`✅ PR #${prNumber} merged successfully!`);
+                                }
+                                catch (mergeError) {
+                                    console.error('❌ Failed to merge PR:', mergeError);
+                                    await client.addComment(task.id, `❌ **Merge Failed**\n\n` +
+                                        `Could not merge PR: ${mergeError instanceof Error ? mergeError.message : String(mergeError)}\n\n` +
+                                        `Please merge manually: ${status.prUrl}`, agentUserId || undefined);
+                                }
+                                finally {
+                                    processingTasks.delete(task.id);
+                                }
+                                continue;
+                            }
+                            // Mark as processing
+                            processingTasks.add(task.id);
+                            // Post starting comment
+                            await client.addComment(task.id, `🖥️ **${agentName} Starting**\n\n` +
+                                `**Task:** ${task.title}\n` +
+                                `**Mode:** Terminal (local Claude Code CLI)\n` +
+                                `**Model:** ${CONFIG.claudeModel}\n\n` +
+                                `Working on this task locally...\n\n` +
+                                `---\n*Using local Claude Code*`, agentUserId || undefined);
+                            // Format comments for terminal executor
+                            const formattedComments = comments.map(c => ({
+                                authorName: c.author?.name || 'Unknown',
+                                content: c.content,
+                                createdAt: c.createdAt,
+                            }));
+                            // Check if this is a follow-up (has previous agent activity)
+                            const hasAgentActivity = comments.some(c => isAIAgentComment(c));
+                            const isFollowUp = hasAgentActivity && comments.length > 1;
+                            // Process task using local Claude Code
+                            const result = await processTaskTerminal({
+                                id: task.id,
+                                title: task.title,
+                                description: task.description,
+                                assigneeEmail,
+                            }, CONFIG.defaultProjectPath, formattedComments, isFollowUp);
+                            if (result.success) {
+                                // Post success comment
+                                let successMessage = `🎉 **Implementation Complete!**\n\n`;
+                                if (result.summary) {
+                                    successMessage += `${result.summary}\n\n`;
+                                }
+                                if (result.files && result.files.length > 0) {
+                                    successMessage += `**Files modified:**\n${result.files.map(f => `- \`${f}\``).join('\n')}\n\n`;
+                                }
+                                if (result.prUrl) {
+                                    successMessage += `🔗 **Pull Request:** [${result.prUrl}](${result.prUrl})\n\n`;
+                                    successMessage += `**What's next:**\n` +
+                                        `1. Review the changes in the PR\n` +
+                                        `2. Test the preview deployment\n` +
+                                        `3. Comment "ship it" to merge!\n\n`;
+                                }
+                                successMessage += `---\n*Generated by ${agentName}*`;
+                                await client.addComment(task.id, successMessage, agentUserId || undefined);
+                                // Unassign task so it goes back to user
+                                await client.reassignTask(task.id, null).catch(err => {
+                                    console.log(`   ⚠️ Could not unassign task: ${err}`);
+                                });
+                            }
+                            else {
+                                // Post failure comment
+                                await client.addComment(task.id, `❌ **Processing Failed**\n\n` +
+                                    `Error: ${result.error}\n\n` +
+                                    `---\n` +
+                                    `💡 **To try again:** Comment "retry" or "try again"\n` +
+                                    `💡 **To ship existing PR:** Comment "ship it"`, agentUserId || undefined);
+                            }
+                            processingTasks.delete(task.id);
+                        }
+                        catch (error) {
+                            console.error(`❌ Failed to process task ${task.id}:`, error);
+                            processingTasks.delete(task.id);
+                            await client.addComment(task.id, `❌ **Processing Failed**\n\n` +
+                                `Error: ${error instanceof Error ? error.message : String(error)}\n\n` +
+                                `---\n` +
+                                `💡 **To try again:** Comment "retry" or "try again"`, agentUserId || undefined).catch(() => { });
                         }
                     }
                 }
@@ -717,33 +1019,182 @@ function showHelp() {
 @gracefultools/astrid-sdk - AI Agent Worker
 
 Usage:
-  npx astrid-agent                 Start polling for tasks
+  npx astrid-agent                 Start polling for tasks (API mode)
+  npx astrid-agent --terminal      Start polling using local Claude Code CLI
+  npx astrid-agent serve           Start webhook server (for always-on servers)
   npx astrid-agent <taskId>        Process a specific task
   npx astrid-agent --help          Show this help
 
-Environment Variables:
-  ASTRID_OAUTH_CLIENT_ID       OAuth client ID
-  ASTRID_OAUTH_CLIENT_SECRET   OAuth client secret
-  ASTRID_OAUTH_LIST_ID         List ID to monitor
+Modes:
+
+  API MODE (Default)
+  ------------------
+  Best for: Cloud servers, CI/CD, when you don't have Claude Code CLI installed
+
+  Uses Claude Agent SDK API to process tasks remotely.
+
+  Environment:
+    ASTRID_OAUTH_CLIENT_ID       OAuth client ID
+    ASTRID_OAUTH_CLIENT_SECRET   OAuth client secret
+    ASTRID_OAUTH_LIST_ID         List ID to monitor
+    ANTHROPIC_API_KEY            For Claude tasks
+
+  Example:
+    npx astrid-agent              # Starts polling (API mode)
+
+  TERMINAL MODE (--terminal)
+  --------------------------
+  Best for: Local development, when you have Claude Code CLI installed
+
+  Uses your local Claude Code CLI (spawn) to process tasks.
+  Enables remote control of your local Claude Code from Astrid.
+
+  Environment:
+    ASTRID_TERMINAL_MODE=true    Enable terminal mode (or use --terminal flag)
+    CLAUDE_MODEL                 Model to use (default: opus)
+    CLAUDE_MAX_TURNS             Max turns per execution (default: 50)
+    DEFAULT_PROJECT_PATH         Project directory (default: current dir)
+
+  Example:
+    npx astrid-agent --terminal
+    # Or with environment variable:
+    ASTRID_TERMINAL_MODE=true npx astrid-agent
+    # With custom options:
+    npx astrid-agent --terminal --model=sonnet --cwd=/path/to/project
+
+  WEBHOOK MODE (serve)
+  --------------------
+  Best for: Always-on servers with permanent IP (VPS, fly.io, etc.)
 
-  ANTHROPIC_API_KEY            For Claude tasks
-  OPENAI_API_KEY               For OpenAI tasks
-  GEMINI_API_KEY               For Gemini tasks
+  Astrid sends tasks directly to your server via webhook.
 
-  GITHUB_TOKEN                 For cloning repositories
-  POLL_INTERVAL_MS             Polling interval (default: 30000)
-  MAX_BUDGET_USD               Max budget per task (default: 10.0)
+  Environment:
+    ASTRID_WEBHOOK_SECRET        Secret from Astrid settings
+    ASTRID_CALLBACK_URL          Callback URL (optional)
+
+  Example:
+    npx astrid-agent serve --port=3001
+
+Common Environment Variables:
+  # AI Provider Keys
+  ANTHROPIC_API_KEY            For Claude tasks (required)
+  OPENAI_API_KEY               For OpenAI tasks (optional)
+  GEMINI_API_KEY               For Gemini tasks (optional)
+
+  # GitHub (for repository access)
+  GITHUB_TOKEN                 For cloning private repositories
+
+Quick Start (Terminal Mode):
+  # 1. Install Claude Code CLI and astrid-sdk
+  npm install -g @anthropic-ai/claude-code @gracefultools/astrid-sdk
+
+  # 2. Set up environment
+  export ANTHROPIC_API_KEY=sk-ant-...
+  export ASTRID_OAUTH_CLIENT_ID=...
+  export ASTRID_OAUTH_CLIENT_SECRET=...
+  export ASTRID_OAUTH_LIST_ID=...
+
+  # 3. Start in terminal mode
+  cd /your/project
+  npx astrid-agent --terminal
+
+  # Now create a task in Astrid and assign to claude@astrid.cc
+  # Your local Claude Code will process it!
+
+Quick Start (API Mode):
+  # 1. Install globally
+  npm install -g @gracefultools/astrid-sdk
+
+  # 2. Set up environment (same as above)
+  # 3. Start polling
+  npx astrid-agent
 `);
 }
+async function startWebhookServer(port) {
+    // Check for required environment variables
+    const webhookSecret = process.env.ASTRID_WEBHOOK_SECRET;
+    if (!webhookSecret) {
+        console.error(`❌ ASTRID_WEBHOOK_SECRET not configured
+
+To set up:
+1. Go to Settings -> AI Agent Settings in Astrid
+2. Configure your webhook URL: http://your-server:${port}/webhook
+3. Copy the webhook secret to your .env file:
+
+   ASTRID_WEBHOOK_SECRET=<your-secret-here>
+`);
+        process.exit(1);
+    }
+    // Check for at least one AI provider
+    const hasProvider = CONFIG.anthropicApiKey || CONFIG.openaiApiKey || CONFIG.geminiApiKey;
+    if (!hasProvider) {
+        console.warn(`⚠️  No AI provider keys configured. Add at least one:
+   ANTHROPIC_API_KEY=sk-ant-...  (for Claude)
+   OPENAI_API_KEY=sk-...         (for OpenAI)
+   GEMINI_API_KEY=AIza...        (for Gemini)
+`);
+    }
+    // Import and start the server from the server module
+    try {
+        const { startServer } = await import('../server/index.js');
+        await startServer({
+            port,
+            webhookSecret,
+            callbackUrl: process.env.ASTRID_CALLBACK_URL,
+        });
+    }
+    catch (error) {
+        if (error.message?.includes('express')) {
+            console.error(`❌ Express not installed. Install it with:
+   npm install express
+`);
+        }
+        else {
+            console.error(`❌ Failed to start server:`, error);
+        }
+        process.exit(1);
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes('--help') || args.includes('-h')) {
         showHelp();
         process.exit(0);
     }
-    if (args.length > 0 && !args[0].startsWith('-')) {
+    // Parse --terminal flag
+    if (args.includes('--terminal')) {
+        CONFIG.terminalMode = true;
+    }
+    // Parse --model flag
+    const modelArg = args.find(a => a.startsWith('--model='));
+    if (modelArg) {
+        CONFIG.claudeModel = modelArg.split('=')[1];
+    }
+    // Parse --cwd flag
+    const cwdArg = args.find(a => a.startsWith('--cwd='));
+    if (cwdArg) {
+        CONFIG.defaultProjectPath = cwdArg.split('=')[1];
+    }
+    // Parse --max-turns flag
+    const maxTurnsArg = args.find(a => a.startsWith('--max-turns='));
+    if (maxTurnsArg) {
+        CONFIG.claudeMaxTurns = parseInt(maxTurnsArg.split('=')[1], 10) || 50;
+    }
+    // Handle 'serve' command
+    if (args[0] === 'serve') {
+        let port = 3001;
+        const portArg = args.find(a => a.startsWith('--port='));
+        if (portArg) {
+            port = parseInt(portArg.split('=')[1], 10) || 3001;
+        }
+        await startWebhookServer(port);
+        return;
+    }
+    // Handle specific task ID (first non-flag argument)
+    const taskIdArg = args.find(a => !a.startsWith('-') && a !== 'serve');
+    if (taskIdArg) {
         // Process a specific task
-        const taskId = args[0];
+        const taskId = taskIdArg;
         console.log(`\n🎯 Processing task: ${taskId}`);
         const client = new astrid_oauth_js_1.AstridOAuthClient();
         const taskResult = await client.getTask(taskId);
@@ -751,18 +1202,68 @@ async function main() {
             console.error(`❌ Failed to get task: ${taskResult.error}`);
             process.exit(1);
         }
-        // TODO: Clone repository based on task's list configuration
-        // For now, use current directory
-        const repoPath = process.cwd();
-        await processTask({
-            id: taskResult.data.id,
-            title: taskResult.data.title,
-            description: taskResult.data.description,
-            assigneeEmail: taskResult.data.assigneeEmail,
-        }, repoPath);
+        const projectPath = CONFIG.defaultProjectPath;
+        if (CONFIG.terminalMode) {
+            console.log(`\n🖥️  Terminal mode enabled`);
+            const result = await processTaskTerminal({
+                id: taskResult.data.id,
+                title: taskResult.data.title,
+                description: taskResult.data.description,
+                assigneeEmail: getAssigneeEmail(taskResult.data),
+            }, projectPath);
+            if (!result.success) {
+                console.error(`❌ Task failed: ${result.error}`);
+                process.exit(1);
+            }
+            console.log(`\n✅ Task completed successfully`);
+            if (result.prUrl) {
+                console.log(`   PR: ${result.prUrl}`);
+            }
+        }
+        else {
+            await processTask({
+                id: taskResult.data.id,
+                title: taskResult.data.title,
+                description: taskResult.data.description,
+                assigneeEmail: getAssigneeEmail(taskResult.data),
+            }, projectPath);
+        }
+        return;
+    }
+    // Default: Run polling worker
+    if (CONFIG.terminalMode) {
+        console.log(`
+🖥️  Starting terminal mode...
+
+   Terminal mode uses your local Claude Code CLI to process tasks.
+   This enables remote control of your local Claude Code from Astrid.
+
+   Settings:
+   - Model: ${CONFIG.claudeModel}
+   - Max turns: ${CONFIG.claudeMaxTurns}
+   - Project path: ${CONFIG.defaultProjectPath}
+
+   Polling for tasks every ${CONFIG.pollIntervalMs / 1000}s...
+
+`);
+        await runWorkerTerminal();
     }
     else {
-        // Run worker loop
+        console.log(`
+🔄 Starting polling mode (API)...
+
+   Polling is ideal for:
+   - Local devices behind NAT/firewalls
+   - Laptops and home servers
+   - Intermittent connectivity
+
+   For terminal mode (uses local Claude Code CLI):
+   npx astrid-agent --terminal
+
+   For always-on servers with permanent IPs, consider:
+   npx astrid-agent serve --port=3001
+
+`);
         await runWorker();
     }
 }