Remote Code Agents

Remote Code Agents

Core Principle

When facing long-running tasks, complex analysis, or workloads better suited for dedicated compute resources, delegate them to remote Claude Code agent containers rather than executing locally.

Note: This skill supports both Claude Code agents (production-ready) and OpenRouter agents (⚠️ experimental, multi-model support).

When to Use This Skill

Always Use When:

• Long-running analysis that would block current workflow (> 5 minutes)
• Resource-intensive tasks like full codebase analysis or performance profiling
• Parallel workload distribution across multiple specialized agents
• Background research that doesn't block current development

Example Scenarios:

• Code review of large pull requests
• Security audit of entire codebase
• Performance optimization analysis
• Documentation generation for multiple modules
• Test generation for legacy code
• Dependency update research

Environment Configuration

Remote code agents require the following environment variables:

# Required: API endpoint for your remote agents
export REMOTE_AGENT_API_URL="http://your-agent-host:8080"

# Required: API key for authentication
export REMOTE_AGENT_API_KEY="your-secure-api-key"

# Optional: Default agent type
export REMOTE_AGENT_DEFAULT_TYPE="general"

Note: Never commit API keys or internal endpoints to version control. Use:

• .env files (gitignored)
• Secret management systems (Vault, AWS Secrets Manager)
• CI/CD secret variables

Agent Types

General Agent

Use for: Coding, debugging, refactoring, feature implementation

AGENT_TYPE=general

Research Agent

Use for: Analysis, documentation, architecture review, research

AGENT_TYPE=research

Testing Agent

Use for: Code review, test generation, QA analysis

AGENT_TYPE=testing

Integration Patterns

1. Command-Line Delegation

If you have the claude-task CLI installed:

# Submit a task
TASK_ID=$(claude-task submit \
  "Analyze this codebase for performance bottlenecks in API endpoints" \
  --repo https://github.com/org/repo \
  --type research)

# Check status later
claude-task status $TASK_ID

# Wait for completion
claude-task wait $TASK_ID

2. API-Based Delegation

Using curl or HTTP clients:

# Submit task
curl -X POST "${REMOTE_AGENT_API_URL}/tasks" \
  -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Review this code for security vulnerabilities",
    "repo_url": "https://github.com/org/repo",
    "branch": "main",
    "agent_type": "testing"
  }'

# Response: {"task_id": "uuid", "status": "submitted"}

# Check status
curl -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
  "${REMOTE_AGENT_API_URL}/tasks/${TASK_ID}"

# Get results
curl -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
  "${REMOTE_AGENT_API_URL}/tasks/${TASK_ID}/output"

3. CI/CD Integration

GitLab CI Example

code-review:
  stage: review
  script:
    - |
      TASK_ID=$(curl -X POST "${REMOTE_AGENT_API_URL}/tasks" \
        -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
        -H "Content-Type: application/json" \
        -d "{
          \"prompt\": \"Review this merge request for bugs and security issues\",
          \"repo_url\": \"${CI_REPOSITORY_URL}\",
          \"branch\": \"${CI_COMMIT_REF_NAME}\",
          \"agent_type\": \"testing\"
        }" | jq -r '.task_id')

      # Wait for completion (with timeout)
      for i in {1..60}; do
        STATUS=$(curl -s -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
          "${REMOTE_AGENT_API_URL}/tasks/${TASK_ID}" | jq -r '.status')

        [ "$STATUS" = "completed" ] && break
        sleep 10
      done

      # Get and display results
      curl -s -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
        "${REMOTE_AGENT_API_URL}/tasks/${TASK_ID}/output"
  only:
    - merge_requests

GitHub Actions Example

- name: Delegate to Remote Agent
  env:
    REMOTE_AGENT_API_URL: ${{ secrets.REMOTE_AGENT_API_URL }}
    REMOTE_AGENT_API_KEY: ${{ secrets.REMOTE_AGENT_API_KEY }}
  run: |
    TASK_ID=$(curl -X POST "${REMOTE_AGENT_API_URL}/tasks" \
      -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "prompt": "Generate tests for new features",
        "repo_url": "${{ github.repository }}",
        "agent_type": "testing"
      }' | jq -r '.task_id')

    echo "Task submitted: ${TASK_ID}"

4. From Current Session

When working interactively and you need to delegate:

# Explain to user what you're doing
echo "This analysis will take ~15 minutes. Delegating to remote agent..."

# Submit task
TASK_ID=$(curl -X POST "${REMOTE_AGENT_API_URL}/tasks" \
  -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Perform comprehensive security audit of authentication system",
    "repo_url": "https://github.com/org/repo",
    "agent_type": "research"
  }' | jq -r '.task_id')

echo "Task ID: ${TASK_ID}"
echo "You can check status with: curl -H 'X-API-Key: ${REMOTE_AGENT_API_KEY}' ${REMOTE_AGENT_API_URL}/tasks/${TASK_ID}"

Task Lifecycle

States

• pending: Task queued, waiting for agent
• processing: Agent actively working on task
• completed: Task finished successfully
• failed: Task encountered errors

Monitoring

# List all tasks
curl -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
  "${REMOTE_AGENT_API_URL}/tasks"

# Filter by status
curl -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
  "${REMOTE_AGENT_API_URL}/tasks?status=completed"

# Get available agents
curl -H "X-API-Key: ${REMOTE_AGENT_API_KEY}" \
  "${REMOTE_AGENT_API_URL}/agents"

Best Practices

1. Clear Task Descriptions

Be specific in your prompts:

❌ Bad: "Fix bugs" ✅ Good: "Review the authentication module for security vulnerabilities, focusing on JWT validation and password hashing"

2. Choose Appropriate Agent Type

• General: Implementation, debugging, refactoring
• Research: Analysis, documentation, investigation
• Testing: Reviews, test generation, QA

3. Don't Wait for Long Tasks

For tasks > 5 minutes:

# Submit and continue working
TASK_ID=$(submit_task "Long analysis task")
echo "Check later: claude-task status ${TASK_ID}"

# Return to it later when needed

4. Security Considerations

• Never expose API keys in code
• Use environment variables or secret management
• Rotate API keys regularly
• Limit agent access to necessary repositories only

5. Repository Access

Ensure remote agents can access repositories:

• Use public repos, OR
• Configure SSH keys/tokens on agent host, OR
• Use repository mirrors accessible to agents

Setting Up Remote Agents

If you want to set up your own remote agent infrastructure:

Requirements

• Docker-capable server (Linux, macOS, Windows)
• Anthropic API key
• Network accessibility (VPN, Tailscale, or public IP)

Basic Setup

# Create agent directory
mkdir -p ~/claude-agents

# Configure environment
cat > ~/claude-agents/.env <<EOF
ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
API_KEY=your-secure-random-api-key
EOF

# Deploy using Docker Compose
# (See repository examples for docker-compose.yml)

docker-compose up -d

Recommended: Use Private Network

• Tailscale, ZeroTier, or WireGuard VPN
• Avoid exposing to public internet
• Use mTLS if public exposure required

Integration with Other Skills

Combines With:

• git-platform-cli: Get repo URLs for delegation
• code-review: Delegate reviews to testing agent
• test-driven-development: Generate tests via testing agent
• systematic-debugging: Delegate root cause analysis

Example Combined Workflow:

# 1. Get current branch/repo info (git-platform-cli)
REPO_URL=$(git remote get-url origin)
BRANCH=$(git branch --show-current)

# 2. Delegate code review (remote-code-agents)
TASK_ID=$(claude-task submit \
  "Review changes in ${BRANCH} for bugs, security, and performance" \
  --repo "${REPO_URL}" \
  --type testing)

# 3. Continue local work while agent reviews

# 4. Later: Check results
claude-task status ${TASK_ID}

Commitment

When delegating to remote agents, I will:

• Use appropriate agent type for the task
• Provide clear, specific task descriptions
• Configure environment variables, never hardcode credentials
• Inform user when delegating long-running tasks
• Monitor task status for time-sensitive work
• Consider security implications of repository access
• Document task IDs for later reference
• Choose delegation over local execution for resource-intensive work

Note: This skill requires external infrastructure. Ensure remote agents are configured and accessible before use.