ajarbot/CLAUDE_CODE_SETUP.md

Claude Agent SDK Setup

Use your Claude Pro subscription OR API key with ajarbot - no separate server needed.

What is the Agent SDK?

The Claude Agent SDK lets you use Claude directly from Python using either:

• Your Pro subscription (unlimited usage within Pro limits)
• Your API key (pay-per-token)

The SDK automatically handles authentication and runs Claude in-process - no FastAPI server required.

Quick Start

1. Install Dependencies

pip install -r requirements.txt

This installs claude-agent-sdk along with all other dependencies.

2. Choose Your Mode

Set AJARBOT_LLM_MODE in your .env file (or leave it unset for default):

# Use Claude Pro subscription (default - recommended for personal use)
AJARBOT_LLM_MODE=agent-sdk

# OR use pay-per-token API
AJARBOT_LLM_MODE=api
ANTHROPIC_API_KEY=sk-ant-...

3. Authenticate (Agent SDK mode only)

If using agent-sdk mode, authenticate with Claude CLI:

# Install Claude CLI (if not already installed)
# Download from: https://claude.ai/download

# Login with your Claude account
claude auth login

This opens a browser window to authenticate with your claude.ai account.

4. Run Your Bot

Windows:

run.bat

Linux/Mac:

python ajarbot.py

That's it! No separate server to manage.

Architecture Comparison

Old Setup (Deprecated)

Telegram/Slack → ajarbot → FastAPI Server (localhost:8000) → Claude Code SDK → Claude

New Setup (Current)

Telegram/Slack → ajarbot → Claude Agent SDK → Claude (Pro OR API)

The new setup eliminates the FastAPI server, reducing complexity and removing an extra process.

Mode Details

Agent SDK Mode (Default)

Pros:

• Uses Pro subscription (unlimited within Pro limits)
• No API key needed
• Higher context window (200K tokens)
• Simple authentication via Claude CLI

Cons:

• Requires Node.js and Claude CLI installed
• Subject to Pro subscription rate limits
• Not suitable for multi-user production

Setup:

# .env file
AJARBOT_LLM_MODE=agent-sdk

# Authenticate once
claude auth login

API Mode

Pros:

• No CLI authentication needed
• Predictable pay-per-token pricing
• Works in any environment (no Node.js required)
• Better for production/multi-user scenarios

Cons:

• Costs money per API call
• Requires managing API keys

Setup:

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

Cost Comparison

Mode	Cost Model	Best For
Agent SDK (Pro)	$20/month flat rate	Heavy personal usage
API (pay-per-token)	~$0.25-$3 per 1M tokens	Light usage, production

With default Haiku model, API mode costs approximately:

• ~$0.04/day for moderate personal use (1000 messages/month)
• ~$1.20/month for light usage

Pre-Flight Checks

The ajarbot.py launcher runs automatic checks before starting:

Agent SDK mode checks:

• Python 3.10+
• Node.js available
• Claude CLI authenticated
• Config file exists

API mode checks:

• Python 3.10+
• .env file exists
• ANTHROPIC_API_KEY is set
• Config file exists

Run health check manually:

python ajarbot.py --health

Troubleshooting

"Node.js not found"

Agent SDK mode requires Node.js. Either:

1. Install Node.js from https://nodejs.org
2. Switch to API mode (set AJARBOT_LLM_MODE=api)

"Claude CLI not authenticated"

# Check authentication status
claude auth status

# Re-authenticate
claude auth logout
claude auth login

"Agent SDK not available"

pip install claude-agent-sdk

If installation fails, switch to API mode.

Rate Limits (Agent SDK mode)

If you hit Pro subscription limits:

• Wait for limit refresh (usually 24 hours)
• Switch to API mode temporarily:

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

"ANTHROPIC_API_KEY not set" (API mode)

Create a .env file in the project root:

cp .env.example .env
# Edit .env and add your API key

Get your API key from: https://console.anthropic.com/settings/keys

Migration from Old Setup

If you previously used the FastAPI server (claude_code_server.py):

1. Remove old environment variables:

   # Delete these from .env
   USE_CLAUDE_CODE_SERVER=true
   CLAUDE_CODE_SERVER_URL=http://localhost:8000
   

2. Set new mode:

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

3. Stop the old server (no longer needed):

   • The claude_code_server.py process can be stopped
   • It's no longer used

4. Run with new launcher:

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

See MIGRATION.md for detailed migration guide.

Features

All ajarbot features work in both modes:

• 15 tools (file ops, system commands, Gmail, Calendar, Contacts)
• Multi-platform adapters (Slack, Telegram)
• Memory system with hybrid search
• Task scheduling
• Google integration (Gmail, Calendar, Contacts)
• Usage tracking (API mode only)

Security

Agent SDK mode:

• Uses your Claude.ai authentication
• No API keys to manage
• Credentials stored by Claude CLI (secure)
• Runs entirely on localhost

API mode:

• API key in .env file (gitignored)
• Environment variable isolation
• No data leaves your machine except to Claude's API

Both modes are suitable for personal bots. API mode is recommended for production/multi-user scenarios.

Sources

• Claude Agent SDK GitHub
• Claude CLI Download
• Anthropic API Documentation