@gracefultools/astrid-sdk 0.4.2 → 0.6.0

package/README.md

@@ -5,30 +5,171 @@ AI agent SDK for automated coding tasks with Claude, OpenAI, and Gemini.
 ## Installation
 
 ```bash
-npm install @gracefultools/astrid-sdk
+npm install -g @gracefultools/astrid-sdk
 ```
 
 ## Quick Start
 
-### CLI Usage
+### Three Execution Modes
 
-Run the agent worker to poll for tasks:
+| Mode | Command | Best For |
+|------|---------|----------|
+| **API** | `npx astrid-agent` | Cloud execution via Claude Agent SDK API |
+| **Terminal** | `npx astrid-agent --terminal` | Local Claude Code CLI (remote control) |
+| **Webhook** | `npx astrid-agent serve` | Always-on servers (fly.io, VPS, AWS) |
+
+### Terminal Mode (Remote Control Your Local Claude Code)
+
+Uses your local Claude Code CLI to process tasks. Enables remote control of your local Claude Code from Astrid.
 
 ```bash
-# Set up environment variables
+# Prerequisites: Install Claude Code CLI
+npm install -g @anthropic-ai/claude-code
+
+# Set up environment
+export ANTHROPIC_API_KEY=sk-ant-...
 export ASTRID_OAUTH_CLIENT_ID=your_client_id
 export ASTRID_OAUTH_CLIENT_SECRET=your_client_secret
 export ASTRID_OAUTH_LIST_ID=your_list_id
-export ANTHROPIC_API_KEY=sk-ant-...  # For Claude
 
-# Start the worker
+# Start in terminal mode
+cd /your/project
+npx astrid-agent --terminal
+
+# With options
+npx astrid-agent --terminal --model=sonnet --cwd=/path/to/project --max-turns=100
+
+# Or via environment variable
+ASTRID_TERMINAL_MODE=true npx astrid-agent
+```
+
+**How it works:**
+1. Agent polls Astrid for tasks assigned to AI agents
+2. When a task is found, it spawns the local Claude Code CLI with `--print`
+3. Claude Code executes in your project directory
+4. Results are posted back to Astrid as comments
+5. Session IDs are stored for resumption support
+
+### API Mode (Default)
+
+Uses Claude Agent SDK API for cloud execution. Best for CI/CD and servers.
+
+```bash
+# Set up environment
+export ANTHROPIC_API_KEY=sk-ant-...
+export ASTRID_OAUTH_CLIENT_ID=your_client_id
+export ASTRID_OAUTH_CLIENT_SECRET=your_client_secret
+export ASTRID_OAUTH_LIST_ID=your_list_id
+
+# Start polling for tasks (API mode)
 npx astrid-agent
+```
 
-# Or process a specific task
-npx astrid-agent <taskId>
+### Webhook Mode (For Always-On Servers)
+
+Receives instant task notifications via webhook. Requires a permanent IP or domain.
+
+```bash
+# Set up environment
+export ANTHROPIC_API_KEY=sk-ant-...
+export ASTRID_WEBHOOK_SECRET=your_webhook_secret
+
+# Start webhook server
+npx astrid-agent serve --port=3001
+
+# Optional: Install express for the server
+npm install express
+```
+
+Then configure your webhook URL in Astrid Settings.
+
+## Environment Variables
+
+| Variable | Mode | Description |
+|----------|------|-------------|
+| **AI Providers** | All | |
+| `ANTHROPIC_API_KEY` | All | Anthropic API key (for Claude) |
+| `OPENAI_API_KEY` | All | OpenAI API key |
+| `GEMINI_API_KEY` | All | Google Gemini API key |
+| **Polling/Terminal Mode** | Polling, Terminal | |
+| `ASTRID_OAUTH_CLIENT_ID` | Polling, Terminal | OAuth client ID from Astrid |
+| `ASTRID_OAUTH_CLIENT_SECRET` | Polling, Terminal | OAuth client secret |
+| `ASTRID_OAUTH_LIST_ID` | Polling, Terminal | List ID to monitor for tasks |
+| **Terminal Mode** | Terminal | |
+| `ASTRID_TERMINAL_MODE` | Terminal | Enable terminal mode (or use --terminal flag) |
+| `CLAUDE_MODEL` | Terminal | Model to use (default: opus) |
+| `CLAUDE_MAX_TURNS` | Terminal | Max turns per execution (default: 50) |
+| `DEFAULT_PROJECT_PATH` | Terminal | Project directory (default: current dir) |
+| **Webhook Mode** | Webhook | |
+| `ASTRID_WEBHOOK_SECRET` | Webhook | Secret from Astrid webhook settings |
+| `ASTRID_CALLBACK_URL` | Webhook | Optional callback URL |
+| **Other** | All | |
+| `GITHUB_TOKEN` | All | GitHub token for cloning private repos |
+| `POLL_INTERVAL_MS` | Polling, Terminal | Poll interval (default: 30000) |
+| `MAX_BUDGET_USD` | API | Max budget per task (default: 10.0) |
+
+## Supported AI Providers
+
+The SDK automatically routes tasks to the correct provider based on the assignee email:
+
+| Agent Email | Provider | Model |
+|-------------|----------|-------|
+| `claude@astrid.cc` | Claude | claude-sonnet-4 |
+| `openai@astrid.cc` | OpenAI | gpt-4o |
+| `gemini@astrid.cc` | Gemini | gemini-2.0-flash |
+
+## Deployment Examples
+
+### Fly.io (Webhook Mode)
+
+```toml
+# fly.toml
+app = "astrid-agent"
+primary_region = "iad"
+
+[http_service]
+  internal_port = 3001
+
+[env]
+  PORT = "3001"
+```
+
+```bash
+fly secrets set ANTHROPIC_API_KEY=sk-ant-...
+fly secrets set ASTRID_WEBHOOK_SECRET=...
+fly deploy
+```
+
+### Docker (Webhook Mode)
+
+```dockerfile
+FROM node:20-slim
+RUN npm install -g @gracefultools/astrid-sdk express
+WORKDIR /app
+EXPOSE 3001
+CMD ["npx", "astrid-agent", "serve", "--port=3001"]
 ```
 
-### Programmatic Usage
+### PM2 (Polling Mode)
+
+```bash
+# ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'astrid-agent',
+    script: 'npx',
+    args: 'astrid-agent',
+    env: {
+      ANTHROPIC_API_KEY: 'sk-ant-...',
+      ASTRID_OAUTH_CLIENT_ID: '...',
+      ASTRID_OAUTH_CLIENT_SECRET: '...',
+      ASTRID_OAUTH_LIST_ID: '...'
+    }
+  }]
+}
+```
+
+## Programmatic Usage
 
 ```typescript
 import {
@@ -72,81 +213,45 @@ if (planResult.success && planResult.plan) {
 }
 ```
 
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `ASTRID_OAUTH_CLIENT_ID` | Yes | OAuth client ID from Astrid |
-| `ASTRID_OAUTH_CLIENT_SECRET` | Yes | OAuth client secret |
-| `ASTRID_OAUTH_LIST_ID` | Yes | List ID to monitor for tasks |
-| `ANTHROPIC_API_KEY` | For Claude | Anthropic API key |
-| `OPENAI_API_KEY` | For OpenAI | OpenAI API key |
-| `GEMINI_API_KEY` | For Gemini | Google Gemini API key |
-| `GITHUB_TOKEN` | For repos | GitHub token for cloning |
-| `POLL_INTERVAL_MS` | No | Poll interval (default: 30000) |
-| `MAX_BUDGET_USD` | No | Max budget per task (default: 10.0) |
-
-## AI Providers
-
-The SDK supports three AI providers:
-
-### Claude (Recommended)
-
-Uses the Claude Agent SDK for native tool use:
-- Best code quality
-- Native file editing
-- Real test execution
-
-```typescript
-import { planWithClaude, executeWithClaude } from '@gracefultools/astrid-sdk'
-```
-
-### OpenAI
+## CLI Reference
 
-Uses GPT-4 with function calling:
+```bash
+# Show help
+npx astrid-agent --help
 
-```typescript
-import { planWithOpenAI, executeWithOpenAI } from '@gracefultools/astrid-sdk'
-```
+# API mode (default - cloud execution)
+npx astrid-agent
 
-### Gemini
+# Terminal mode (local Claude Code CLI)
+npx astrid-agent --terminal
+npx astrid-agent --terminal --model=sonnet --cwd=/path/to/project
 
-Uses Gemini with function calling:
+# Process a specific task
+npx astrid-agent <taskId>
+npx astrid-agent --terminal <taskId>
 
-```typescript
-import { planWithGemini, executeWithGemini } from '@gracefultools/astrid-sdk'
+# Webhook mode
+npx astrid-agent serve --port=3001
 ```
 
-## Astrid OAuth Client
-
-The SDK includes a client for the Astrid OAuth API:
-
-```typescript
-import { AstridOAuthClient } from '@gracefultools/astrid-sdk'
-
-const client = new AstridOAuthClient()
-
-// Get lists
-const lists = await client.getLists()
-
-// Get tasks
-const tasks = await client.getTasks(listId)
-
-// Get a specific task
-const task = await client.getTask(taskId)
+## Comparison: Terminal vs API vs Webhook
 
-// Add a comment
-await client.addComment(taskId, 'Work in progress...')
-
-// Complete a task
-await client.completeTask(taskId)
-```
+| Feature | Terminal | API | Webhook |
+|---------|----------|-----|---------|
+| Execution | Local CLI | Cloud API | Cloud API |
+| Requires Claude Code CLI | Yes | No | No |
+| Permanent IP needed | No | No | Yes |
+| Works behind NAT | Yes | Yes | No |
+| Session resume | Yes | No | No |
+| Task notification | ~30s poll | ~30s poll | Instant |
+| Best for | Local dev | CI/CD, servers | Always-on servers |
+| Project access | Local files | Clones repo | Clones repo |
 
-## Keeping Updated
+## Updating
 
 ```bash
 # Update to latest version
-npm update @gracefultools/astrid-sdk
+npm update -g @gracefultools/astrid-sdk
 ```
 
 ## License

package/dist/bin/cli.d.ts

@@ -5,7 +5,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
  */

package/dist/bin/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/bin/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/bin/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}