Refactor: Clean up obsolete files and organize codebase structure
This commit removes deprecated modules and reorganizes code into logical directories: Deleted files (superseded by newer systems): - claude_code_server.py (replaced by agent-sdk direct integration) - heartbeat.py (superseded by scheduled_tasks.py) - pulse_brain.py (unused in production) - config/pulse_brain_config.py (obsolete config) Created directory structure: - examples/ (7 example files: example_*.py, demo_*.py) - tests/ (5 test files: test_*.py) Updated imports: - agent.py: Removed heartbeat module and all enable_heartbeat logic - bot_runner.py: Removed heartbeat parameter from Agent initialization - llm_interface.py: Updated deprecated claude_code_server message Preserved essential files: - hooks.py (for future use) - adapters/skill_integration.py (for future use) - All Google integration tools (Gmail, Calendar, Contacts) - GLM provider code (backward compatibility) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
256
CLAUDE_CODE_SETUP.md
Normal file
256
CLAUDE_CODE_SETUP.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# 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/)
|
||||
Reference in New Issue
Block a user