npm - @segosolutions/auto-task - Versions diffs - 1.0.1 → 1.2.0 - Mend

@segosolutions/auto-task 1.0.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,133 +1,276 @@
 # @segosolutions/auto-task
 [![npm version](https://img.shields.io/npm/v/@segosolutions/auto-task.svg)](https://www.npmjs.com/package/@segosolutions/auto-task)
+[![npm downloads](https://img.shields.io/npm/dm/@segosolutions/auto-task.svg)](https://www.npmjs.com/package/@segosolutions/auto-task)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-required-blueviolet.svg)](https://claude.ai/code)
-Background task monitor for [Sego PM](https://sego.pm) - automatically processes high-confidence tasks using Claude.
+> Automated task processing for [Sego PM](https://sego.pm) - runs Claude locally to process high-confidence tasks in the background.
+```
+   ____                      _         _            _____         _
+  / ___|  ___  __ _  ___    / \  _   _| |_ ___     |_   _|_ _ ___| | __
+  \___ \ / _ \/ _` |/ _ \  / _ \| | | | __/ _ \ _____| |/ _` / __| |/ /
+   ___) |  __/ (_| | (_) |/ ___ \ |_| | || (_) |_____| | (_| \__ \   <
+  |____/ \___|\__, |\___/_/   \_\__,_|\__\___/       |_|\__,_|___/_|\_\
+              |___/
+```
+---
+## What Does This Do?
+The Sego Auto-Task Monitor watches your Sego PM projects and automatically processes tasks that meet your confidence threshold. When a client submits a request, the monitor:
+1. **Detects** new client requests or eligible tasks
+2. **Claims** the task (prevents duplicate processing)
+3. **Executes** using your local Claude CLI with full project context
+4. **Completes** and moves the task to review with detailed output
+This means less manual work for you and faster turnaround for your clients.
+---
 ## Prerequisites
-Before installing, ensure you have:
+> **Important:** You must have Claude Code CLI installed and authenticated before using this tool.
-1. **Node.js 18+** - [Download here](https://nodejs.org/)
-2. **Claude Code CLI** - Install and authenticate:
-   ```bash
-   npm install -g @anthropic-ai/claude-code
-   claude auth login
-   ```
-3. **Sego PM API Key** - Generate from [Developer Settings](https://sego.pm/developer/api-keys)
+### Claude Code CLI (Required)
+The monitor uses the Claude Code CLI to process tasks locally. Install and authenticate:
+```bash
+# Install globally
+npm install -g @anthropic-ai/claude-code
+# Authenticate (opens browser)
+claude auth login
+# Verify it works
+claude --version
+```
+> **Note:** Claude Code requires an Anthropic account with API access.
+### Sego PM API Key (Required)
+Generate an API key from your [Developer Settings](https://sego.pm/developer/api-keys) in Sego PM.
+---
 ## Quick Start
 Get up and running in under 5 minutes:
 ```bash
-# 1. Install globally
+# Step 1: Install globally
 npm install -g @segosolutions/auto-task
-# 2. Run the interactive setup
+# Step 2: Run the interactive setup wizard
 sego-auto-task init
-# 3. Start monitoring (from your project directory)
+# Step 3: Start monitoring
 sego-auto-task
 ```
 That's it! The monitor will now process eligible tasks automatically.
+### One-Liner (For the impatient)
+```bash
+npm i -g @segosolutions/auto-task && sego-auto-task init
+```
+---
 ## Installation
-### Global Install (Recommended)
+### NPM Global (Recommended)
 ```bash
 npm install -g @segosolutions/auto-task
 ```
-### Project Install
+After installation, the `sego-auto-task` command is available globally.
+### NPX (No Install)
+Run without installing:
 ```bash
-npm install --save-dev @sego/auto-task
-npx sego-auto-task --help
+npx @segosolutions/auto-task --help
 ```
-## Usage
+### Yarn Global
-### Basic Usage
+```bash
+yarn global add @segosolutions/auto-task
+```
+### PNPM Global
 ```bash
-# Start monitoring with default settings (connects to https://sego.pm)
-sego-auto-task
+pnpm add -g @segosolutions/auto-task
+```
-# Use environment variables
-export SEGO_API_KEY=sk_live_...
-sego-auto-task
+### Project Local (Dev Dependency)
+Install as a dev dependency for project-specific use:
-# Or pass directly
-sego-auto-task --api-key=sk_live_...
+```bash
+npm install --save-dev @segosolutions/auto-task
+# Run via npx
+npx sego-auto-task
 ```
-### Development Mode
+---
+## Configuration
+### Interactive Setup (Recommended)
+The easiest way to configure is the setup wizard:
 ```bash
-# Connect to local Sego PM instance
-sego-auto-task --api-url=http://localhost:3000
+sego-auto-task init
+```
-# Test without processing tasks
-sego-auto-task --dry-run
+This will:
+- Prompt for your API key
+- Validate the connection
+- Optionally set a project filter
+- Save configuration to `.env`
+### Non-Interactive Setup
+For CI/CD or scripted setups:
+```bash
+SEGO_API_KEY=sk_live_xxx sego-auto-task init --yes
 ```
-### Project-Specific Monitoring
+### Environment Variables
+Create a `.env` file in your project directory (or use `sego-auto-task init`):
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SEGO_API_KEY` | Yes | - | Your Sego PM API key |
+| `SEGO_API_URL` | No | `https://sego.pm` | API endpoint URL |
+| `SEGO_PROJECT_ID` | No | All projects | Filter to a specific project |
+| `SEGO_WORKING_DIR` | No | Current directory | Working directory for Claude |
+| `CONVERSATION_ONLY` | No | `false` | Only handle conversations, skip auto-tasks |
+**Example `.env` file:**
 ```bash
-# Only monitor tasks for a specific project
-sego-auto-task --project-id=cmiursa7x0001qptpaehaq7hg
+# Required
+SEGO_API_KEY=sk_live_your_key_here
+# Optional
+SEGO_API_URL=https://sego.pm
+SEGO_PROJECT_ID=proj_abc123
+SEGO_WORKING_DIR=/path/to/project
+CONVERSATION_ONLY=true  # Only process conversations, skip auto-tasks
 ```
-## CLI Options
+### CLI Options
+All options can be passed via command line (overrides environment variables):
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--api-key <key>` | Sego PM API key | `SEGO_API_KEY` env |
+| `--api-key <key>` | Sego PM API key | `$SEGO_API_KEY` |
 | `--api-url <url>` | Sego PM API URL | `https://sego.pm` |
-| `--project-id <id>` | Only process tasks for this project | All projects |
+| `--project-id <id>` | Filter to specific project | All projects |
 | `--poll <seconds>` | Poll interval for checking tasks | `30` |
 | `--timeout <minutes>` | Task processing timeout | `10` |
 | `--client-request-timeout <minutes>` | Client request analysis timeout | `2` |
-| `--no-sse` | Disable SSE mode | SSE enabled |
-| `--dry-run` | Poll but don't process tasks | `false` |
+| `--no-sse` | Disable real-time SSE mode | SSE enabled |
+| `--dry-run` | Check for tasks without processing | `false` |
+| `--conversation-only` | Only handle conversational sessions, skip auto-task processing | `false` |
 | `--working-dir <path>` | Working directory for Claude | Current directory |
-| `--no-update-check` | Disable update check on startup | Check enabled |
+| `--no-update-check` | Skip update check on startup | Check enabled |
 | `-V, --version` | Show version number | |
 | `-h, --help` | Show help | |
-## Environment Variables
+---
+## Usage Examples
-Create a `.env` file in your working directory or export these variables:
+### Basic Usage
 ```bash
-# Required
-SEGO_API_KEY=sk_live_...              # Your Sego PM API key
+# Start with default settings (uses .env)
+sego-auto-task
-# Optional
-SEGO_API_URL=https://sego.pm          # API URL (default: https://sego.pm)
-SEGO_PROJECT_ID=...                   # Filter to specific project
-SEGO_WORKING_DIR=/path/to/project     # Working directory for Claude
+# Use inline API key
+sego-auto-task --api-key=sk_live_xxx
+```
+### Development Mode
+```bash
+# Connect to local Sego PM instance
+sego-auto-task --api-url=http://localhost:3000
+# Test without processing (see what would be processed)
+sego-auto-task --dry-run
+```
+### Project-Specific Monitoring
+```bash
+# Only monitor a specific project
+sego-auto-task --project-id=cmiursa7x0001qptpaehaq7hg
+```
+### Custom Timeouts
-# Advanced
-AUTO_TASK_POLL_INTERVAL_MS=30000      # Poll interval in milliseconds
-AUTO_TASK_TIMEOUT_MS=600000           # Task timeout in milliseconds
-AUTO_TASK_SSE_ENABLED=true            # Enable/disable SSE mode
+```bash
+# Longer timeout for complex tasks (30 minutes)
+sego-auto-task --timeout=30 --client-request-timeout=5
+# Faster polling (check every 15 seconds)
+sego-auto-task --poll=15
 ```
+### Polling Only (No Real-time)
+```bash
+# Disable SSE, rely only on polling
+sego-auto-task --no-sse --poll=60
+```
+### Conversation Only (No Auto-Task Processing)
+```bash
+# Only handle conversational chat sessions, skip automatic task processing
+sego-auto-task --conversation-only --project-id=cmiursa7x0001qptpaehaq7hg
+# This mode will:
+# - Process conversational sessions (chat back-and-forth)
+# - Skip non-conversational client request analysis
+# - Skip automatic backlog task processing
+# - Skip polling for eligible tasks
+```
+---
 ## How It Works
-The monitor runs in hybrid mode:
+The monitor runs in hybrid mode combining real-time and polling:
 ### SSE Mode (Real-time)
 - Listens for client request events via Server-Sent Events
 - Processes new requests immediately as they arrive
-- Uses local Claude to analyze and shape tasks
+- Requires `--project-id` for targeted monitoring
 ### Polling Mode (Batch)
 - Checks every 30 seconds (configurable) for eligible tasks
 - Processes tasks where:
   - Project has auto-task enabled
@@ -136,20 +279,36 @@ The monitor runs in hybrid mode:
 ### Processing Flow
-1. **Detect** - New task or client request is found
-2. **Claim** - Task status updated to `IN_PROGRESS`
-3. **Execute** - Claude processes the task with full context
-4. **Complete** - Task moves to `IN_REVIEW` with output attached
+```
+New Request/Task Found
+        |
+        v
+   Claim Task (mark IN_PROGRESS)
+        |
+        v
+   Run Claude with project context
+        |
+        v
+   Complete (move to IN_REVIEW)
+        |
+        v
+   Post results as task comment
+```
+---
+## Project Configuration (Sego PM)
-## Project Configuration
+Enable auto-task processing for your project in Sego PM:
-Enable auto-task processing for your project:
+### Via Web UI
-1. Go to your project settings in Sego PM
+1. Go to your project settings
 2. Enable "Auto-Task Processing"
 3. Set your confidence threshold (recommended: 0.85)
-Or via API:
+### Via API
 ```bash
 curl -X PATCH https://sego.pm/api/mcp/projects/{projectId}/auto-task \
   -H "Authorization: Bearer sk_live_..." \
@@ -157,56 +316,23 @@ curl -X PATCH https://sego.pm/api/mcp/projects/{projectId}/auto-task \
   -d '{"enabled": true, "confidenceThreshold": 0.85}'
 ```
-## Troubleshooting
-### "Claude CLI is not available"
-Ensure Claude Code is installed and authenticated:
-```bash
-npm install -g @anthropic-ai/claude-code
-claude auth login
-claude --version
-```
-### "API key is required"
-Set your API key via environment variable or CLI flag:
-```bash
-export SEGO_API_KEY=sk_live_...
-# or
-sego-auto-task --api-key=sk_live_...
-```
-### Connection Issues
-1. Verify your API key is valid
-2. Check if you can reach the API:
-   ```bash
-   curl -H "Authorization: Bearer sk_live_..." https://sego.pm/api/mcp/tasks
-   ```
-3. For local development, ensure `--api-url` points to your local server
-### Tasks Not Being Processed
-1. Verify auto-task is enabled for the project
-2. Check task AI confidence meets the threshold
-3. Ensure task is in `BACKLOG` status
-4. Run with `--dry-run` to see what would be processed
+---
 ## Running as a Service
-### Using PM2
+### Using PM2 (Recommended)
 ```bash
+# Install PM2
 npm install -g pm2
-# Start the monitor
-pm2 start sego-auto-task --name "sego-monitor" -- --api-key=sk_live_...
+# Start the monitor as a daemon
+pm2 start sego-auto-task --name "sego-monitor" -- --api-key=sk_live_xxx
 # View logs
 pm2 logs sego-monitor
-# Auto-start on boot
+# Auto-restart on reboot
 pm2 save
 pm2 startup
 ```
@@ -225,7 +351,7 @@ Type=simple
 User=your-user
 WorkingDirectory=/path/to/your/project
 Environment=SEGO_API_KEY=sk_live_...
-ExecStart=/usr/bin/sego-auto-task
+ExecStart=/usr/local/bin/sego-auto-task
 Restart=always
 RestartSec=10
@@ -233,14 +359,237 @@ RestartSec=10
 WantedBy=multi-user.target
 ```
-Then:
+Then enable and start:
 ```bash
 sudo systemctl enable sego-auto-task
 sudo systemctl start sego-auto-task
+sudo systemctl status sego-auto-task
+```
+### Using launchd (macOS)
+Create `~/Library/LaunchAgents/com.segosolutions.auto-task.plist`:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.segosolutions.auto-task</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/sego-auto-task</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>SEGO_API_KEY</key>
+        <string>sk_live_...</string>
+    </dict>
+    <key>WorkingDirectory</key>
+    <string>/path/to/your/project</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/tmp/sego-auto-task.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/sego-auto-task.err</string>
+</dict>
+</plist>
 ```
+Then load:
+```bash
+launchctl load ~/Library/LaunchAgents/com.segosolutions.auto-task.plist
+```
+### Using Docker
+```dockerfile
+FROM node:20-alpine
+# Install Claude CLI and auto-task
+RUN npm install -g @anthropic-ai/claude-code @segosolutions/auto-task
+# Set working directory
+WORKDIR /app
+# Environment variables (or mount .env)
+ENV SEGO_API_KEY=sk_live_...
+CMD ["sego-auto-task"]
+```
+Build and run:
+```bash
+docker build -t sego-auto-task .
+docker run -d --name sego-monitor sego-auto-task
+```
+---
+## Troubleshooting
+### "Claude CLI is not available"
+The monitor requires the Claude Code CLI to be installed and authenticated.
+```bash
+# Install Claude CLI
+npm install -g @anthropic-ai/claude-code
+# Authenticate with Anthropic
+claude auth login
+# Verify installation
+claude --version
+```
+If you see permission errors, try:
+```bash
+sudo npm install -g @anthropic-ai/claude-code
+```
+Or fix npm permissions (recommended for macOS/Linux):
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc  # or ~/.zshrc
+source ~/.bashrc
+```
+### "API key is required"
+Set your API key via one of these methods:
+```bash
+# Option 1: Environment variable
+export SEGO_API_KEY=sk_live_your_key
+# Option 2: CLI flag
+sego-auto-task --api-key=sk_live_your_key
+# Option 3: .env file
+echo "SEGO_API_KEY=sk_live_your_key" > .env
+# Option 4: Interactive setup
+sego-auto-task init
+```
+### "Invalid API key or unable to connect"
+1. **Verify your API key is correct and not expired**
+2. **Check network connectivity:**
+   ```bash
+   curl -I https://sego.pm
+   ```
+3. **Test API authentication:**
+   ```bash
+   curl -H "Authorization: Bearer sk_live_..." https://sego.pm/api/mcp/tasks
+   ```
+4. **For local development**, ensure `--api-url` points to your local server:
+   ```bash
+   sego-auto-task --api-url=http://localhost:3000
+   ```
+### Tasks Not Being Processed
+Check these common causes:
+1. **Project settings:** Auto-task must be enabled for the project in Sego PM
+2. **Task status:** Task must be in `BACKLOG` status
+3. **Confidence threshold:** Task's AI confidence must meet or exceed the project threshold
+4. **Test with dry-run:**
+   ```bash
+   sego-auto-task --dry-run
+   ```
+   This shows what tasks would be processed without actually processing them.
+5. **Check the console output** for any error messages or skipped tasks
+### SSE Connection Issues
+If real-time events aren't working:
+1. **Ensure `--project-id` is set** (required for SSE mode):
+   ```bash
+   sego-auto-task --project-id=your_project_id
+   ```
+2. **Check that the API URL supports SSE**
+3. **Try disabling SSE** to use polling only:
+   ```bash
+   sego-auto-task --no-sse
+   ```
+### Monitor Keeps Stopping
+If the monitor exits unexpectedly:
+1. **Check logs for error messages**
+2. **Increase timeout** for long-running tasks:
+   ```bash
+   sego-auto-task --timeout=30
+   ```
+3. **Use PM2** for automatic restarts:
+   ```bash
+   pm2 start sego-auto-task --name sego --restart-delay=5000
+   ```
+### Permission Errors on macOS
+If you get permission errors during global install:
+```bash
+# Fix npm permissions (recommended)
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
+source ~/.zshrc
+# Then reinstall
+npm install -g @segosolutions/auto-task
+```
+### "Command not found: sego-auto-task"
+The npm global bin directory may not be in your PATH:
+```bash
+# Find where npm installs global packages
+npm config get prefix
+# Add to PATH (adjust path as needed)
+export PATH="$(npm config get prefix)/bin:$PATH"
+# Make permanent
+echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
+```
+---
 ## Development
+Want to contribute or run from source?
+### Setup
 ```bash
 # Clone the repository
 git clone https://github.com/nickgs/sego-pm.git
@@ -250,7 +599,7 @@ cd sego-pm/auto-task-monitor
 pnpm install
 # Run in development mode
-pnpm dev -- --api-key=sk_dev_...
+pnpm dev -- --api-key=sk_dev_xxx
 # Type check
 pnpm typecheck
@@ -259,12 +608,105 @@ pnpm typecheck
 pnpm build
 ```
+### Project Structure
+```
+auto-task-monitor/
+├── src/
+│   ├── index.ts          # CLI entry point
+│   ├── monitor.ts        # Main monitor logic
+│   ├── claude-runner.ts  # Claude CLI integration
+│   ├── config.ts         # Configuration loading
+│   ├── init.ts           # Setup wizard
+│   └── version-check.ts  # Update notifications
+├── dist/                 # Built output
+├── package.json
+└── README.md
+```
+### Testing Locally
+```bash
+# Run with local API
+pnpm dev -- --api-url=http://localhost:3000 --dry-run
+# Build and test the built version
+pnpm build
+node dist/index.cjs --help
+```
+---
+## Changelog
+### v1.0.1
+- Fixed repository URLs in package.json
+- Improved error messages
+### v1.0.0
+- Initial release
+- SSE and polling hybrid mode
+- Interactive setup wizard
+- Automatic update checks
+- Claude CLI integration
+---
+## FAQ
+### How does this differ from processing tasks in the Sego PM web UI?
+The auto-task monitor runs Claude **locally** on your machine, using your local codebase context. This means:
+- Claude has access to your full project files
+- Processing happens on your hardware
+- No additional API costs beyond your existing Claude subscription
+### What confidence threshold should I use?
+We recommend starting with **0.85** (85%). This ensures only well-understood tasks are automatically processed. You can lower it as you gain confidence in the system.
+### Can I run multiple monitors?
+Yes, but only one monitor should process each project to avoid conflicts. Use `--project-id` to assign different projects to different monitors.
+### Does this work with self-hosted Sego PM?
+Yes! Use `--api-url` to point to your self-hosted instance:
+```bash
+sego-auto-task --api-url=https://your-sego-instance.com
+```
+### How do I stop the monitor?
+Press `Ctrl+C` for graceful shutdown, or:
+```bash
+# If using PM2
+pm2 stop sego-monitor
+# If using systemd
+sudo systemctl stop sego-auto-task
+```
+---
+## Support
+- **Documentation:** [https://sego.pm/docs](https://sego.pm/docs)
+- **Issues:** [GitHub Issues](https://github.com/nickgs/sego-pm/issues)
+- **Email:** [hello@segosolutions.com](mailto:hello@segosolutions.com)
+---
 ## License
 MIT - see [LICENSE](./LICENSE)
-## Links
+---
-- [Sego PM](https://sego.pm) - AI-Assisted Project Management
-- [Documentation](https://sego.pm/docs)
-- [GitHub Issues](https://github.com/nickgs/sego-pm/issues)
+<p align="center">
+  Built with Claude by <a href="https://segosolutions.com">Sego Solutions</a>
+</p>