@task-shepherd/agent

Task Shepherd AI Agent

AI agent service for automated project analysis and task processing with Claude integration.

Installation

Option 1: Using npx (Recommended)

# No installation needed - always uses latest version
npx @task-shepherd/agent init
npx @task-shepherd/agent start

Option 2: Global Install

# Install globally for permanent CLI access
npm install -g @task-shepherd/agent

# Then use directly
task-shepherd-agent init
task-shepherd-agent start

Note: npx is recommended as it ensures you're always using the latest version without managing global installations.

Quick Start

1. Initialize Agent

task-shepherd-agent init

This interactive wizard will guide you through:

• Configuring your Task Shepherd organization connection
• Setting up your Claude API key
• Selecting your agent identity strategy
• Configuring ports and service settings
• Setting agent capabilities

Before running init, you'll need:

• Organization ID: From your Task Shepherd organization settings
• API URL: Your organization's GraphQL endpoint (e.g., https://your-org.api.taskshepherd.com/graphql)
• API Key: Generated from Task Shepherd dashboard → Settings → API Keys
• Claude API Key: From Anthropic Console → API Keys (starts with sk-ant-api03-)

2. Register Workspaces

After initialization, register the projects you want the agent to work on:

# Register current directory as a workspace
task-shepherd-agent workspace register

# Or register a specific directory
task-shepherd-agent workspace register --path /path/to/your/project

# Or scan common development directories automatically
task-shepherd-agent workspace scan-common

# View registered workspaces
task-shepherd-agent workspace list

3. Start Agent Service

task-shepherd-agent start

The agent will:

• Connect to your Task Shepherd instance
• Sync registered workspaces with the backend
• Begin polling for assigned work
• Provide analytics dashboard at http://localhost:8548

Alternative: Environment Variables (Single Organization Only)

You can also configure the agent using environment variables for single organization deployments:

# Set your Task Shepherd API connection
export TASK_SHEPHERD_API_URL="https://your-org.api.taskshepherd.com/graphql"
export TASK_SHEPHERD_API_KEY="tks_your_api_key_here"

# Set your Claude API key
export CLAUDE_API_KEY="sk-ant-api03-your_claude_key_here"

# Optional: Customize ports
export PORT=8547
export WEB_PORT=8548

⚠️ Note: Environment variables only support single organization mode. For multi-organization support, use the init wizard and config file approach.

Managing Multiple Organizations

The agent supports working with multiple Task Shepherd organizations simultaneously. After initialization:

To add additional organizations:

• Edit the config file at ~/.task-shepherd-agent/config.json
• Add organizations to the organizations array:

{
  "agentId": "your-agent-id",
  "organizations": [
    {
      "id": "org-1-id",
      "name": "Organization 1",
      "apiUrl": "https://org1.api.taskshepherd.com/graphql",
      "apiKey": "tks_org1_key",
      "enabled": true
    },
    {
      "id": "org-2-id",
      "name": "Organization 2",
      "apiUrl": "https://org2.api.taskshepherd.com/graphql",
      "apiKey": "tks_org2_key",
      "enabled": true
    }
  ]
}

• Restart the agent: task-shepherd-agent start

The agent will poll all enabled organizations for work and process tasks from any of them.

Features

🤖 AI-Powered Analysis

• Comprehensive project reviews with scoring
• Development plan generation
• Story implementation guidance
• Code quality assessment

📊 Analytics Dashboard

• Real-time performance metrics
• Token usage tracking and cost monitoring
• Success rate analytics
• Worker performance comparisons

⚡ Efficient Processing

• Lightweight in-memory queue system
• Configurable concurrency limits
• Automatic retry for failed jobs
• Real-time progress tracking

🔧 Workspace Management

• Automatic workspace discovery
• Multi-technology support (React, Node.js, Python, etc.)
• Dynamic service registration
• Flexible configuration options

Configuration

Environment Variables

# Required: Task Shepherd API
TASK_SHEPHERD_API_URL="https://api.taskshepherd.com/graphql"
TASK_SHEPHERD_API_KEY="tks_your_api_key"

# Required: AI Provider
CLAUDE_API_KEY="sk-ant-api03-your_key"

# Optional: Service Configuration
PORT=8547                    # Agent API port
WEB_PORT=8548               # Dashboard port
MAX_CONCURRENT_JOBS=3       # Concurrent processing limit
TOKEN_RATE_LIMIT=10000      # Daily token limit

Workspace Registration

Register workspaces for the agent to process:

# Register current directory
task-shepherd-agent workspace register

# Register specific directory
task-shepherd-agent workspace register --path /path/to/project

# Scan common development directories
task-shepherd-agent workspace scan-common

# List registered workspaces
task-shepherd-agent workspace list

CLI Commands

Note: Replace task-shepherd-agent with npx @task-shepherd/agent if using npx.

Agent Management

task-shepherd-agent init                    # Initialize agent
task-shepherd-agent start                   # Start agent service
task-shepherd-agent status                  # Check agent status
task-shepherd-agent stop                    # Stop agent service

Workspace Management

task-shepherd-agent workspace register     # Register workspace
task-shepherd-agent workspace list         # List workspaces
task-shepherd-agent workspace sync         # Sync with backend
task-shepherd-agent workspace validate     # Validate configuration

Analysis Operations

task-shepherd-agent analysis start --type project_review
task-shepherd-agent analysis status --job <job-id>
task-shepherd-agent analysis list

API Endpoints

When running, the agent provides these endpoints:

Analysis Operations

# Create analysis job
POST http://localhost:8547/api/analysis
{
  "project": {
    "id": "project-123",
    "name": "My Project"
  },
  "analysisType": "project_review",
  "workspacePath": "/path/to/project"
}

# Get job status
GET http://localhost:8547/api/analysis/{jobId}

# List active jobs
GET http://localhost:8547/api/analysis

Health Monitoring

# Health check
GET http://localhost:8547/api/health

# Usage statistics
GET http://localhost:8547/api/usage/stats

# Rate limits
GET http://localhost:8547/api/usage/rate-limit

Analytics Dashboard

Access the web dashboard at http://localhost:8548 for:

• Real-time Metrics: Active jobs, queue status, success rates
• Performance Analytics: Completion times, throughput analysis
• Cost Monitoring: Token usage, API costs, efficiency metrics
• Historical Data: Trends, patterns, optimization insights

Supported Analysis Types

Project Review

Comprehensive analysis including:

• Code quality assessment
• Architecture evaluation
• Security considerations
• Performance recommendations
• Technical debt identification

Development Plan

Strategic implementation guidance:

• Feature breakdown and prioritization
• Timeline estimation
• Risk assessment
• Resource requirements
• Technology recommendations

Story Implementation

Detailed implementation guidance:

• Technical approach recommendations
• Code examples and patterns
• Testing strategies
• Integration considerations

Workspace Support

The agent automatically detects and supports:

Frontend Technologies

• React, Vue, Angular, Svelte
• TypeScript, JavaScript
• CSS frameworks (Tailwind, Bootstrap)
• Build tools (Vite, Webpack, Parcel)

Backend Technologies

• Node.js, Python, Java, Go, Rust
• Express, FastAPI, Spring Boot
• GraphQL, REST APIs
• Database integrations

Infrastructure

• Docker and containerization
• CI/CD pipelines
• Cloud platforms (AWS, Azure, GCP)
• Monitoring and logging

Production Deployment

Docker Deployment

FROM node:18-alpine
RUN npm install -g @task-shepherd/agent
EXPOSE 8547 8548
CMD ["task-shepherd-agent", "start"]

Environment Configuration

# Production settings
NODE_ENV=production
TASK_SHEPHERD_API_URL="https://api.taskshepherd.com/graphql"
CLAUDE_API_KEY="your-production-key"
MAX_CONCURRENT_JOBS=5
TOKEN_RATE_LIMIT=50000

Health Monitoring

# Health check endpoint for load balancers
curl http://localhost:8547/api/health

# Readiness check
curl http://localhost:8547/api/ready

Troubleshooting

Connection Issues

# Test Task Shepherd API connection
curl -H "x-api-key: $TASK_SHEPHERD_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "query { __typename }"}' \
     $TASK_SHEPHERD_API_URL

Agent Issues

# Check agent status
task-shepherd-agent status

# Validate workspace configuration
task-shepherd-agent workspace validate

# View agent logs
tail -f ~/.task-shepherd-agent/logs/agent.log

Common Solutions

• API Key Invalid: Verify API key in Task Shepherd dashboard
• Claude API Issues: Check Claude API key and quotas
• Workspace Not Found: Re-register workspace with correct path
• Port Conflicts: Change PORT environment variable

API Key Management

Get your API keys from:

• Task Shepherd API Key: Your Task Shepherd instance dashboard → Settings → API Keys
• Claude API Key: Anthropic Console → API Keys

Set environment variables or use a .env file:

TASK_SHEPHERD_API_KEY="tks_..."
CLAUDE_API_KEY="sk-ant-api03-..."

License

Proprietary software - see LICENSE.md for usage terms.

Support

• Check agent status: task-shepherd-agent status
• View logs: ~/.task-shepherd-agent/logs/
• Health check: http://localhost:8547/api/health