Package Exports

@task-shepherd/agent
@task-shepherd/agent/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@task-shepherd/agent) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Task Shepherd AI Agent

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

Installation

npm install -g @task-shepherd/agent

Quick Start

1. Initialize Agent

task-shepherd-agent init

2. Configure API Connection

# Set your Task Shepherd API connection
export TASK_SHEPHERD_API_URL="https://your-instance.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"

3. Start Agent Service

task-shepherd-agent start

The agent will:

Connect to your Task Shepherd instance
Register available workspaces
Begin processing assigned work
Provide analytics dashboard at http://localhost:8548

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 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

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