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

```bash
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):

```bash
# 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:

```bash
# 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:**
```bash
run.bat
```

**Linux/Mac:**
```bash
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:**
```bash
# .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:**
```bash
# .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:
```bash
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"
```bash
# Check authentication status
claude auth status

# Re-authenticate
claude auth logout
claude auth login
```

### "Agent SDK not available"
```bash
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:
  ```bash
  # 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:
```bash
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:**
   ```bash
   # Delete these from .env
   USE_CLAUDE_CODE_SERVER=true
   CLAUDE_CODE_SERVER_URL=http://localhost:8000
   ```

2. **Set new mode:**
   ```bash
   # 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:**
   ```bash
   run.bat  # Windows
   python ajarbot.py  # Linux/Mac
   ```

See [MIGRATION.md](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](https://github.com/anthropics/anthropic-sdk-python)
- [Claude CLI Download](https://claude.ai/download)
- [Anthropic API Documentation](https://docs.anthropic.com/)