ajarbot/MIGRATION.md

Migration Guide: FastAPI Server to Agent SDK

This guide helps you upgrade from the old FastAPI server setup to the new Claude Agent SDK integration.

What Changed?

Old Architecture (Deprecated)

Bot → FastAPI Server (localhost:8000) → Claude Code SDK → Claude

• Required running claude_code_server.py in separate terminal
• Only worked with Pro subscription
• More complex setup with multiple processes

New Architecture (Current)

Bot → Claude Agent SDK → Claude (Pro OR API)

• Single process (no separate server)
• Works with Pro subscription OR API key
• Simpler setup and operation
• Same functionality, less complexity

Migration Steps

Step 1: Update Dependencies

Pull latest code and reinstall dependencies:

git pull
pip install -r requirements.txt

This installs claude-agent-sdk and removes deprecated dependencies.

Step 2: Update Environment Configuration

Edit your .env file:

Remove these deprecated variables:

# DELETE THESE
USE_CLAUDE_CODE_SERVER=true
CLAUDE_CODE_SERVER_URL=http://localhost:8000

Add new mode selection:

# ADD THIS
AJARBOT_LLM_MODE=agent-sdk  # Use Pro subscription (default)
# OR
AJARBOT_LLM_MODE=api        # Use pay-per-token API

If using API mode, ensure you have:

ANTHROPIC_API_KEY=sk-ant-...

If using agent-sdk mode, authenticate once:

claude auth login

Step 3: Stop Old Server

The FastAPI server is no longer needed:

1. Stop any running claude_code_server.py processes
2. Remove it from startup scripts/systemd services
3. Optionally archive or delete claude_code_server.py (kept for reference)

Step 4: Use New Launcher

Old way:

# Terminal 1
python claude_code_server.py

# Terminal 2
python bot_runner.py

New way:

# Single command
run.bat              # Windows
python ajarbot.py    # Linux/Mac

The new launcher:

• Runs pre-flight checks (Node.js, authentication, config)
• Sets sensible defaults (agent-sdk mode)
• Starts bot in single process
• No separate server needed

Step 5: Test Your Setup

Run health check:

python ajarbot.py --health

Expected output (agent-sdk mode):

============================================================
Ajarbot Pre-Flight Checks
============================================================

✓ Python 3.10.x
✓ Node.js found: v18.x.x
✓ Claude CLI authenticated

[Configuration Checks]
✓ Config file found: config/adapters.local.yaml

Pre-flight checks complete!
============================================================

Step 6: Verify Functionality

Test that everything works:

1. Start the bot:

   run.bat  # or python ajarbot.py
   

2. Send a test message via Slack/Telegram

3. Verify tools work:

   • Ask bot to read a file
   • Request calendar events
   • Test scheduled tasks

All features are preserved:

• 15 tools (file ops, Gmail, Calendar, Contacts)
• Memory system with hybrid search
• Multi-platform adapters
• Task scheduling

Mode Comparison

Choose the mode that fits your use case:

Feature	Agent SDK Mode	API Mode
Cost	$20/month (Pro)	~$0.25-$3/M tokens
Setup	claude auth login	API key in .env
Requirements	Node.js + Claude CLI	Just Python
Best For	Personal heavy use	Light use, production
Rate Limits	Pro subscription limits	API rate limits

Switching Between Modes

You can switch anytime by editing .env:

# Switch to agent-sdk
AJARBOT_LLM_MODE=agent-sdk

# Switch to API
AJARBOT_LLM_MODE=api
ANTHROPIC_API_KEY=sk-ant-...

No code changes needed - just restart the bot.

Troubleshooting

"Node.js not found" (Agent SDK mode)

Option 1: Install Node.js

# Download from https://nodejs.org
# Or via package manager:
winget install OpenJS.NodeJS  # Windows
brew install node             # Mac
sudo apt install nodejs       # Ubuntu/Debian

Option 2: Switch to API mode

# In .env
AJARBOT_LLM_MODE=api
ANTHROPIC_API_KEY=sk-ant-...

"Claude CLI not authenticated"

# Check status
claude auth status

# Re-authenticate
claude auth logout
claude auth login

If Claude CLI isn't installed, download from: https://claude.ai/download

"Agent SDK not available"

pip install claude-agent-sdk

If installation fails, use API mode instead.

Old Environment Variables Still Set

Check your .env file for deprecated variables:

# These should NOT be in your .env:
USE_CLAUDE_CODE_SERVER=true
CLAUDE_CODE_SERVER_URL=http://localhost:8000
USE_AGENT_SDK=true
USE_DIRECT_API=true

Delete them and use AJARBOT_LLM_MODE instead.

Bot Works But Features Missing

Ensure you have latest code:

git pull
pip install -r requirements.txt --upgrade

All features from the old setup are preserved:

• Tools system (15 tools)
• Memory with hybrid search
• Scheduled tasks
• Google integration
• Multi-platform adapters

Performance Issues

Agent SDK mode:

• May hit Pro subscription rate limits
• Temporary solution: Switch to API mode
• Long-term: Wait for limit reset (usually 24 hours)

API mode:

• Check usage with: python -c "from usage_tracker import UsageTracker; UsageTracker().print_summary()"
• Costs shown in usage_data.json
• Default Haiku model is very cheap (~$0.04/day moderate use)

Rollback Plan

If you need to rollback to the old setup:

1. Restore old .env settings:

   USE_CLAUDE_CODE_SERVER=true
   CLAUDE_CODE_SERVER_URL=http://localhost:8000
   

2. Start the old server:

   python claude_code_server.py
   

3. Run bot with old method:

   python bot_runner.py
   

However, the new setup is recommended - same functionality with less complexity.

What's Backward Compatible?

All existing functionality is preserved:

• Configuration files (config/adapters.local.yaml, config/scheduled_tasks.yaml)
• Memory database (memory_workspace/memory.db)
• User profiles (memory_workspace/users/)
• Google OAuth tokens (config/google_oauth_token.json)
• Tool definitions and capabilities
• Adapter integrations

You can safely migrate without losing data or functionality.

Benefits of New Setup

1. Simpler operation: Single command to start
2. Flexible modes: Choose Pro subscription OR API
3. Automatic checks: Pre-flight validation before starting
4. Better errors: Clear messages about missing requirements
5. Less complexity: No multi-process coordination
6. Same features: All 15 tools, adapters, scheduling preserved

Need Help?

• Review CLAUDE_CODE_SETUP.md for detailed mode documentation
• Check README.md for quick start guides
• Run python ajarbot.py --health to diagnose issues
• Open an issue if you encounter problems

Summary

Before:

# Terminal 1
python claude_code_server.py

# Terminal 2
python bot_runner.py

After:

# .env
AJARBOT_LLM_MODE=agent-sdk  # or "api"

# Single command
run.bat  # Windows
python ajarbot.py  # Linux/Mac

Same features, less complexity, more flexibility.