gh-joshuaoliphant-claude-plugins-plugins-adw-bootstrap/skills/adw-bootstrap/docs/usage-modes.md

ADW Usage Modes: Subscription vs API

Overview

ADW infrastructure supports two distinct usage modes, enabling both interactive development and automated workflows without code changes.

Mode A: Claude Max Subscription

What It Is

Run Claude Code through your Claude Max subscription without needing API keys.

How It Works

User with Claude Max subscription
    ↓
Logged in to Claude Code CLI
    ↓
ADW executes: claude -p "prompt"
    ↓
Claude Code uses subscription auth
    ↓
Prompt executed, results returned

No API key configuration needed - authentication happens automatically through your subscription.

Setup

Zero configuration required:

# Just run the ADWs
./adws/adw_prompt.py "analyze this code"

# No .env file needed
# No API key needed
# Works immediately

Requirements

• Active Claude Max subscription
• Claude Code CLI installed and logged in
• User must be authenticated

Advantages

✅ Simple - No configuration, just works ✅ Secure - No API keys to manage ✅ Interactive - Perfect for development ✅ Immediate - No setup friction

Limitations

❌ User presence required - Can't run headless ❌ Single user - Tied to your subscription ❌ Limited automation - Not ideal for CI/CD ❌ Session-dependent - Must be logged in

Perfect For

• Interactive development
• Local experimentation
• Learning ADWs
• Personal projects
• Quick prototyping

Example Workflow

# Morning: Start development
./adws/adw_chore_implement.py "add user authentication"

# Afternoon: Create another feature
./adws/adw_chore_implement.py "implement password reset"

# Evening: Code review
./adws/adw_prompt.py "review security in auth module"

# All executed through your subscription
# No API key management
# Just works

Mode B: API-Based Programmatic Execution

What It Is

Run Claude Code programmatically using API keys for automated, headless workflows.

How It Works

Environment has ANTHROPIC_API_KEY
    ↓
ADW reads API key from environment
    ↓
ADW executes: claude -p "prompt"
    ↓
Claude Code uses API key for auth
    ↓
Prompt executed, results returned

API key is passed through filtered environment to subprocess.

Setup

Step 1: Create .env file

# Copy template
cp .env.sample .env

# Edit .env
nano .env

Step 2: Add your API key

# .env file
ANTHROPIC_API_KEY=sk-ant-api03-...

# Optional configurations
CLAUDE_CODE_PATH=claude
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=true

Step 3: Secure the file

# Never commit .env
echo ".env" >> .gitignore

# Restrict permissions
chmod 600 .env

Requirements

• Anthropic API key (from console.anthropic.com)
• API access enabled on account
• Claude Code CLI installed

Advantages

✅ Headless - Runs without user interaction ✅ Automatable - Perfect for CI/CD ✅ Multi-user - Not tied to single subscription ✅ Scriptable - Full programmatic control ✅ Reliable - No session dependencies

Limitations

❌ Requires API key - Additional setup ❌ Costs - API usage charges ❌ Key management - Security consideration ❌ Environment config - Must configure .env

Perfect For

• CI/CD pipelines
• Webhook handlers
• Scheduled tasks (cron jobs)
• Server-side automation
• Team automation workflows
• Production deployments

Example Workflows

CI/CD Integration

# .github/workflows/ai-review.yml
name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Set up environment
        run: |
          echo "ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}" > .env

      - name: Run AI review
        run: |
          ./adws/adw_prompt.py "review this PR for security issues"

Webhook Handler

# webhook_server.py
from flask import Flask, request
import subprocess

app = Flask(__name__)

@app.route('/webhook/feature-request', methods=['POST'])
def handle_feature_request():
    data = request.json
    description = data['description']

    # Execute ADW with API key from environment
    subprocess.run([
        './adws/adw_chore_implement.py',
        description
    ])

    return {'status': 'processing'}

Cron Job

# crontab -e

# Run daily code quality check at 2 AM
0 2 * * * cd /path/to/project && ./adws/adw_prompt.py "analyze code quality and suggest improvements" >> /var/log/adw-daily.log 2>&1

Mode Detection

The ADW infrastructure automatically detects which mode to use:

# In agent.py
def get_safe_subprocess_env():
    env = {
        # System variables
        "HOME": os.getenv("HOME"),
        "PATH": os.getenv("PATH"),
        # ...
    }

    # Only add API key if it exists
    api_key = os.getenv("ANTHROPIC_API_KEY")
    if api_key:
        env["ANTHROPIC_API_KEY"] = api_key

    # If no API key, Claude Code uses subscription
    return env

Detection logic:

1. Check if ANTHROPIC_API_KEY exists in environment
2. If yes → API mode (pass key to subprocess)
3. If no → Subscription mode (Claude Code uses logged-in session)

No code changes needed - same scripts work in both modes.

Comparison Matrix

Feature	Subscription Mode	API Mode
Setup Complexity	None	Moderate (API key)
User Presence	Required	Not required
CI/CD Integration	❌ Difficult	✅ Easy
Cost	Subscription price	API usage charges
Security	No key to manage	Must secure API key
Automation	Limited	Full
Interactive Use	✅ Excellent	✅ Works fine
Headless Use	❌ Not practical	✅ Perfect
Multi-user	Per subscription	Shared key possible
Session Management	Must stay logged in	None needed

Switching Between Modes

Subscription → API

# Create .env file
cat > .env << 'EOF'
ANTHROPIC_API_KEY=sk-ant-...
EOF

# Secure it
chmod 600 .env

# Now all ADW executions use API
./adws/adw_prompt.py "test"

API → Subscription

# Remove .env file
rm .env

# Or comment out API key
# ANTHROPIC_API_KEY=sk-ant-...

# Now all ADW executions use subscription
./adws/adw_prompt.py "test"

Same scripts work in both modes - just change environment.

Best Practices

For Subscription Mode

1. Stay logged in

   # Check auth status
   claude --version
   

2. Personal projects

   • Use for local development
   • No .env file needed

3. Quick iteration

   • Fast setup
   • Immediate feedback

For API Mode

1. Secure your keys

   # Never commit
   echo ".env" >> .gitignore
   
   # Restrict permissions
   chmod 600 .env
   
   # Use secrets management in production
   

2. Rotate regularly

   # Update API key periodically
   # Revoke old keys
   

3. Monitor usage

   • Track API consumption
   • Set up billing alerts
   • Monitor costs

4. Use environment-specific keys

   # Development
   ANTHROPIC_API_KEY=sk-ant-dev-...
   
   # Production
   ANTHROPIC_API_KEY=sk-ant-prod-...
   

For Both Modes

1. Document which mode you're using

   # README.md
   
   ## Setup
   
   This project uses Claude Max subscription mode by default.
   For CI/CD, configure ANTHROPIC_API_KEY in .env.
   

2. Test in both modes

   • Ensure portability
   • Validate automation path
   • Document differences

3. Choose based on use case

   • Interactive development → Subscription
   • Automation/CI/CD → API
   • Both are valid

Troubleshooting

Subscription Mode Issues

Problem: "Authentication failed"

# Solution: Re-login to Claude Code
claude login

Problem: "Command not found: claude"

# Solution: Install Claude Code CLI
# [Installation instructions]

Problem: "Session expired"

# Solution: Re-authenticate
claude logout
claude login

API Mode Issues

Problem: "Invalid API key"

# Solution: Check .env file
cat .env | grep ANTHROPIC_API_KEY

# Verify key format: sk-ant-api03-...
# Get new key from console.anthropic.com

Problem: "API key not found"

# Solution: Ensure .env is loaded
# Check file location
ls -la .env

# Verify environment
echo $ANTHROPIC_API_KEY

Problem: "Rate limit exceeded"

# Solution: Implement backoff or use subscription mode
# Reduce parallel executions
# Contact Anthropic for higher limits

Security Considerations

Subscription Mode

✅ Secure by default - No secrets to manage ✅ Session-based - Expires automatically ✅ User-specific - Can't be shared accidentally

⚠️ Physical access - Anyone with terminal access can use ⚠️ Session hijacking - Theoretical risk in shared environments

API Mode

✅ Revocable - Can disable keys anytime ✅ Trackable - Monitor usage per key ✅ Rotatable - Easy to update

⚠️ Key exposure - Must protect .env file ⚠️ Commit risk - Can accidentally commit ⚠️ Scope risk - Key has broad permissions

Protection Strategies

1. For .env files

   # Always in .gitignore
   echo ".env" >> .gitignore
   
   # Restrict permissions
   chmod 600 .env
   
   # Use git secrets scanning
   git secrets --scan
   

2. For production

   # Use secrets managers
   - AWS Secrets Manager
   - HashiCorp Vault
   - GitHub Secrets
   
   # Not .env files in production
   

3. For CI/CD

   # Use repository secrets
   secrets:
     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
   
   # Never hardcode
   # Never commit
   

Recommendation

Start with Subscription Mode

• Simpler setup
• Perfect for learning
• Great for development
• Zero configuration

Migrate to API Mode when needed

• Adding CI/CD
• Implementing webhooks
• Scheduling tasks
• Production deployment

Keep both available

• Developers use subscription
• Automation uses API
• Best of both worlds

Same ADW infrastructure supports both - choose based on context.