AnyTask Worker Guide
Complete guide to the AnyTask Worker system for automated task execution.Table of Contents
- Overview
- Quick Start
- Worker Commands
- Built-in Workflows
- Writing Custom Workflows
- Workflow Syntax Reference
- Available Actions
- Variable Interpolation
- Secret Management
- Workflow Execution
- Examples
- Best Practices
- Troubleshooting
Overview
The AnyTask Worker is an automated task execution system that:- Continuously polls for tasks assigned to your agent
- Executes workflows automatically based on task triggers
- Updates task status and posts progress notes
- Tracks execution attempts and artifacts
- Uses Claude Code for AI-assisted implementation
How It Works
Key Features
- ✅ Built-in workflows for common development tasks
- ✅ Custom workflow support via YAML files
- ✅ Secret management via system keyring
- ✅ Attempt tracking with full execution history
- ✅ Artifact storage for outputs and results
- ✅ Variable interpolation for dynamic workflow configuration
- ✅ Error handling with automatic task updates
Quick Start
1. Set Up Authentication
2. Initialize Workspace
3. Get Your Agent ID
Visit https://anyt.dev/home/agents and copy your agent identifier (e.g.,agent-xxx).
4. Start the Worker
5. Create a Task
Worker Commands
Start Worker
--workspace, -w: Workspace directory (default: current)--workflow: Specific workflow to run (local_dev, feature_development, general_task)--workflows: Custom workflows directory (default: .anyt/workflows)--poll-interval, -i: Polling interval in seconds (default: 5)--max-backoff: Maximum backoff interval in seconds (default: 60)--agent-id, -a: Agent identifier (required)--project-id, -p: Project ID to scope task suggestions
- If
--workflowspecified: Uses that specific workflow only - If
--workflowsspecified: Loads all workflows from that directory - Otherwise: Loads all workflows from
.anyt/workflows/ - Falls back to built-in workflows if not found
- Custom directory (if
--workflowsspecified) - Workspace
.anyt/workflows/(user can override built-ins) - Package built-in workflows
List Workflows
--workflows: Workflows directory (default: .anyt/workflows)
Validate Workflow
Built-in Workflows
The CLI includes three built-in workflows for common development scenarios.1. Local Development (local_dev)
Purpose: Direct implementation on current repository state without branch switching.
Best for:
- Quick iterations and fixes
- Working on current branch
- Local testing
- Simple tasks
task_created: Any newly created tasktask_updated: Any task updated totodostatus
- Analyze task - Uses Claude Haiku to analyze requirements
- Post analysis - Adds analysis to task as note
- Implement changes - Uses Claude Code to implement
- Post implementation - Adds summary to task
- Lint code - Runs
make lint(continues on error) - Run tests - Runs
make test(continues on error) - Commit changes - Creates git commit with task reference
- Mark complete - Updates task to
donestatus
- Working on current branch
- Simple bug fixes
- Quick prototypes
- Local development
2. Feature Development (feature_development)
Purpose: Full feature workflow with proper branch management and testing.
Best for:
- Production features
- Complex implementations
- Tasks requiring thorough testing
- Team collaboration
task_created: Tasks withfeaturelabeltask_updated: Tasks withfeaturelabel updated totodostatus
- Checkout code - Checks out main branch
- Cache dependencies - Caches uv/pnpm dependencies
- Analyze task - Creates detailed implementation plan
- Implement changes - Uses Claude Code to implement
- Lint code - Runs
make lint(fails on error) - Run tests - Runs
make test(fails on error) - Commit changes - Creates detailed git commit
- Mark complete - Updates task to
donestatus
- Posts error note to task
- Creates follow-up bug task for investigation
- Feature development
- Production-ready code
- Tasks requiring tests
- Quality assurance needed
3. General Task Handler (general_task)
Purpose: Catch-all workflow for any TODO task without specific labels.
Best for:
- Generic tasks
- Mixed work types
- Default workflow
- Unclassified tasks
task_created: Any task withtodostatustask_updated: Any task updated totodostatus
- Checkout code - Checks out main branch (no clean)
- Analyze task - Uses Claude to analyze requirements
- Implement changes - Uses Claude Code to implement
- Run tests - Runs
make test(continues on error) - Commit changes - Creates git commit
- Mark complete - Updates task to
donestatus
- Any TODO task
- Mixed work types
- Default handling
- Quick processing
Writing Custom Workflows
Create custom workflows by adding YAML files to.anyt/workflows/ directory.
Basic Workflow Structure
Minimal Workflow Example
Workflow Syntax Reference
Workflow Root
Triggers (on)
Define when the workflow should run:
task_created: Runs when a new task is createdtask_updated: Runs when a task is updated
labels: List of required labels (task must have ALL labels)status: List of valid statuses (task can match ANY status)
Jobs
Steps
Action-based step:On-Failure Handler
Available Actions
Git Actions
anyt/checkout@v1
Checkout git repository to specific branch.
Parameters:
anyt/git-commit@v1
Create git commit with changes.
Parameters:
commit_hash: The SHA of the created commit
Claude/AI Actions
anyt/claude-prompt@v1
Get response from Claude without code execution.
Parameters:
{output}: The Claude response (default:result)tokens_used: Number of tokens consumed
claude-haiku-4-5-20251001(fast, cost-effective)claude-sonnet-4-5-20250929(balanced)claude-opus-4-5(most capable)
anyt/claude-code@v1
Execute Claude Code CLI for implementation.
Parameters:
summary: Implementation summarytokens_used: Number of tokens consumedfiles_modified: List of modified files
Task Actions
anyt/task-update@v1
Update task status or add notes.
Parameters:
backlogtodoin_progressdonecancelled
anyt/task-analyze@v1
Analyze task and post structured analysis.
Parameters:
analysis: Structured analysis resulttokens_used: Number of tokens consumed
anyt/task-detail@v1
Get detailed task information.
Parameters:
identifier: Task identifiertitle: Task titledescription: Task descriptionstatus: Current statuslabels: Task labels
Cache Actions
anyt/cache@v1
Cache dependencies and artifacts.
Parameters:
hashFiles(pattern): Hash of files matching pattern
Testing Actions
anyt/test@v1
Run tests with automatic framework detection.
Parameters:
anyt/build@v1
Build project.
Parameters:
Dry-Run Actions
For testing workflows without external dependencies:anyt/dry-run-claude-prompt@v1anyt/dry-run-claude-code@v1anyt/dry-run-git-commit@v1
Variable Interpolation
Use${{ ... }} syntax to access dynamic values.
Task Variables
Step Outputs
Reference outputs from previous steps:Failure Variables
Available inon-failure handler:
Environment Variables
Access environment variables:Functions
hashFiles(pattern) Calculate hash of files matching pattern:Secret Management
Store sensitive values securely in system keyring.Set Secret
Get Secret
Delete Secret
Use Secrets in Workflows
Test Secret Interpolation
Workflow Execution
Execution Flow
Viewing Execution History
List attempts for a task:Execution Context
Each workflow execution has access to:- Task data: All task fields and metadata
- Step outputs: Results from previous steps
- Environment: Environment variables
- Secrets: Stored secrets via keyring
- Workspace: Current workspace configuration
Examples
Example 1: Simple Bug Fix Workflow
Example 2: Documentation Workflow
Example 3: Multi-Step Feature Workflow
Example 4: Conditional Execution
Best Practices
1. Workflow Organization
DO:- One workflow per purpose/label
- Clear, descriptive workflow names
- Document trigger conditions
- Keep workflows focused and simple
- Create overly complex workflows
- Mix unrelated tasks in one workflow
- Use vague trigger conditions
2. Error Handling
Always include error handlers:3. Timeouts
Set appropriate timeouts:4. Secret Management
DO:- Store all sensitive values as secrets
- Use descriptive secret names
- Test secrets with
anyt worker secret test
- Hardcode API keys in workflows
- Share secrets in workflow files
- Log secret values
5. Variable Usage
Use variables for dynamic content:6. Step Outputs
Reuse outputs from previous steps:7. Git Commits
Include task reference in commits:8. Task Updates
Provide meaningful progress updates:9. Testing
Test workflows before deploying:10. Documentation
Document your workflows:Troubleshooting
Worker Won’t Start
Error:ANYT_API_KEY environment variable not set
--agent-id is required
No workspace config found
Workflow Not Triggering
Check trigger conditions:Workflow Fails
View execution logs:failed step in attempt details.
Common issues:
- Timeout: Increase
timeout-minutes - Missing dependencies: Install required tools
- Permission errors: Check file permissions
- API errors: Verify API key and connectivity
Secret Not Found
Error:Secret 'API_KEY' not found
Claude Code Issues
Error:Claude Code execution failed
- Check Claude Code is installed
- Review prompt for clarity
- Check token limits
Git Commit Fails
Error:Git commit failed
- Check git is configured
- Verify working directory is clean
- Check for merge conflicts
- Ensure branch exists
Performance Issues
Worker is slow:- Reduce
poll-interval(default: 5s) - Check network connectivity
- Optimize workflow steps
- Use faster Claude models
- Increase
timeout-minutes - Break into smaller tasks
- Optimize prompts
- Use parallel execution where possible
Production Deployment
Infrastructure Setup
Prerequisites
System Requirements:- Linux server (Ubuntu 20.04+ or equivalent)
- Python 3.11+ (managed via uv)
- Git configured with user credentials
- Systemd for process management
- 2GB RAM minimum, 4GB+ recommended
- 10GB disk space minimum
- Outbound HTTPS to API endpoint (api.anyt.dev)
- Stable internet connection
- Optional: VPN for accessing private git repositories
Installation
Install AnyTask CLI:Configuration
Environment Configuration
Production Environment (/etc/anyt/environments/production.env):
Workspace Initialization
Initialize Production Workspace:Systemd Service Configuration
Production Worker Service
Create Service File (/etc/systemd/system/anyt-worker-prod.service):
Enable and Start Service
Production Workflows
Feature Development Workflow
Create Workflow (/etc/anyt/workflows/production/feature_development.yaml):
Production Bug Fix Workflow
Create Workflow (/etc/anyt/workflows/production/bug_fix.yaml):
Monitoring and Observability
Logging Configuration
Structured Logging:Metrics Collection
Custom Metrics Script (/usr/local/bin/anyt-metrics.sh):
Health Checks
Health Check Script (/usr/local/bin/anyt-health-check.sh):
Backup and Recovery
Configuration Backup
Disaster Recovery
Recovery Procedure:Performance Optimization
Caching Strategy
Resource Limits
Systemd Resource Controls:Production Checklist
Before going live:- Infrastructure: Server provisioned with required resources
- Installation: AnyTask CLI and Claude Code installed
- Service User: Dedicated
anyt-workeruser created - Configuration: Environment files with correct keys
- Workflows: Production workflows validated and tested
- Systemd: Service files configured with security hardening
- Permissions: File permissions set correctly (600 for secrets)
- Git: Git credentials configured for commits
- Monitoring: Logging and metrics collection configured
- Alerts: Health checks and alert notifications configured
- Backup: Configuration backup scheduled
- Documentation: Runbooks and incident response procedures
- Testing: End-to-end test in staging environment
- Security: Security audit completed