Simplified AI agent service for Task Shepherd project analysis
npm install @task-shepherd/agentAI agent service for automated project analysis and task processing with Claude integration.
bash
No installation needed - always uses latest version
npx @task-shepherd/agent init
npx @task-shepherd/agent start
`$3
bash
Install globally for permanent CLI access
npm install -g @task-shepherd/agentThen use directly
task-shepherd-agent init
task-shepherd-agent start
`Note:
is recommended as it ensures you're always using the latest version without managing global installations.Quick Start
$3
`bash
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.,
)
- API Key: Generated from Task Shepherd dashboard → Settings → API Keys
- Claude API Key: From Anthropic Console → API Keys (starts with sk-ant-api03-)$3
After initialization, register the projects you want the agent to work on:
`bash
Register current directory as a workspace
task-shepherd-agent workspace registerOr register a specific directory
task-shepherd-agent workspace register --path /path/to/your/projectOr scan common development directories automatically
task-shepherd-agent workspace scan-commonView registered workspaces
task-shepherd-agent workspace list
`$3
bash
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
$3
You can also configure the agent using environment variables for single organization deployments:
bash
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.
$3
The agent supports working with multiple Task Shepherd organizations simultaneously. After initialization:
To add additional organizations:
1. Edit the config file at
2. Add organizations to the array:`json
{
"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
}
]
}
`3. Restart the agent:
The agent will poll all enabled organizations for work and process tasks from any of them.
Features
$3
- Comprehensive project reviews with scoring
- Development plan generation
- Story implementation guidance
- Code quality assessment$3
- Real-time performance metrics
- Token usage tracking and cost monitoring
- Success rate analytics
- Worker performance comparisons$3
- Lightweight in-memory queue system
- Configurable concurrency limits
- Automatic retry for failed jobs
- Real-time progress tracking$3
- Automatic workspace discovery
- Multi-technology support (React, Node.js, Python, etc.)
- Dynamic service registration
- Flexible configuration optionsConfiguration
$3
bash
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
`$3
Register workspaces for the agent to process:
bash
Register current directory
task-shepherd-agent workspace registerRegister specific directory
task-shepherd-agent workspace register --path /path/to/projectScan common development directories
task-shepherd-agent workspace scan-commonList registered workspaces
task-shepherd-agent workspace list
`CLI Commands
Note: Replace
with npx @task-shepherd/agent if using npx.$3
`bash
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
`$3
bash
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
`$3
bash
task-shepherd-agent analysis start --type project_review
task-shepherd-agent analysis status --job
task-shepherd-agent analysis list
`API Endpoints
When running, the agent provides these endpoints:
$3
bash
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
`$3
bash
Health check
GET http://localhost:8547/api/healthUsage statistics
GET http://localhost:8547/api/usage/statsRate 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
$3
Comprehensive analysis including:
- Code quality assessment
- Architecture evaluation
- Security considerations
- Performance recommendations
- Technical debt identification$3
Strategic implementation guidance:
- Feature breakdown and prioritization
- Timeline estimation
- Risk assessment
- Resource requirements
- Technology recommendations$3
Detailed implementation guidance:
- Technical approach recommendations
- Code examples and patterns
- Testing strategies
- Integration considerationsWorkspace Support
The agent automatically detects and supports:
$3
- React, Vue, Angular, Svelte
- TypeScript, JavaScript
- CSS frameworks (Tailwind, Bootstrap)
- Build tools (Vite, Webpack, Parcel)$3
- Node.js, Python, Java, Go, Rust
- Express, FastAPI, Spring Boot
- GraphQL, REST APIs
- Database integrations$3
- Docker and containerization
- CI/CD pipelines
- Cloud platforms (AWS, Azure, GCP)
- Monitoring and loggingProduction Deployment
$3
dockerfile
FROM node:18-alpine
RUN npm install -g @task-shepherd/agent
EXPOSE 8547 8548
CMD ["task-shepherd-agent", "start"]
`$3
bash
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
`$3
bash
Health check endpoint for load balancers
curl http://localhost:8547/api/healthReadiness check
curl http://localhost:8547/api/ready
`Troubleshooting
$3
bash
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
`$3
bash
Check agent status
task-shepherd-agent statusValidate workspace configuration
task-shepherd-agent workspace validateView agent logs
tail -f ~/.task-shepherd-agent/logs/agent.log
`$3
- 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 variableAPI Key Management
Get your API keys from:
1. Task Shepherd API Key: Your Task Shepherd instance dashboard → Settings → API Keys
2. Claude API Key: Anthropic Console → API Keys
Set environment variables or use a
file:
`bash
TASK_SHEPHERD_API_KEY="tks_..."
CLAUDE_API_KEY="sk-ant-api03-..."
`License
Proprietary software - see LICENSE.md for usage terms.
Support
- Check agent status:
- View logs: