Development Setup

This guide will help you set up the BILL AI Agent development environment.

Prerequisites

• Bun (v1.0+) - Fast JavaScript runtime (NOT npm/Node.js)

• PostgreSQL (via Supabase)

• Git

• Code Editor (VS Code recommended)

Environment Setup

1. Clone the Repository

git clone https://github.com/your-org/bill-agent.git
cd bill-agent

2. Install Dependencies

# Install all dependencies using Bun
bun install

# Navigate to agent directory and install
cd agent
bun install

# Install website dependencies
cd ../clients/website
bun install

# Install API server dependencies
cd ../bill-api-server
bun install

3. Environment Variables

Create .env file in the project root:

# LLM Services
OPENROUTER_API_KEY=your_openrouter_api_key
OPENAI_API_KEY=your_openai_api_key

# Database (Supabase)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SECRET_KEY=your_secret_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key # Optional, for admin operations

# Twitter Configuration
TWITTER_CLIENT_ID=your_twitter_client_id
TWITTER_CLIENT_SECRET=your_twitter_client_secret
TWITTER_REDIRECT_URI=http://localhost:3000/callback
TWITTER_USERNAME=your_twitter_username

# Twitter Rate Limits
POST_INTERVAL_MIN=50
POST_INTERVAL_MAX=120
POST_LIMIT=20
REPLY_LIMIT=100

# Twitter Context
TWITTER_ENABLE_CONTEXT=true
TWITTER_IMMEDIATE_FETCH_CONTEXT=false # Set to true for testing

# Telegram
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_WEBHOOK_URL=https://your-domain.com/telegram-webhook # Optional

# Website/API Server
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_WS_URL=ws://localhost:3001
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your_recaptcha_site_key
RECAPTCHA_SECRET_KEY=your_recaptcha_secret_key

# News API (Optional)
NEWS_API_KEY=your_newsapi_key

# Logging
LOGGING_WS_URL=ws://localhost:3003
NODE_ENV=development

# Character Engine (Optional)
CHARACTER_ENGINE_API_URL=http://localhost:8000

4. Database Setup

Create Supabase Project

1. Go to Supabase

2. Create a new project

3. Copy the project URL and keys to .env

Run Database Migrations

# Twitter tables
psql $SUPABASE_URL < agent/plugins/twitter/sql/create_tables.sql
psql $SUPABASE_URL < agent/plugins/twitter/sql/context_analysis_schema.sql

# Create storage buckets in Supabase dashboard:
# - tweet_images (for Twitter image storage)

5. Twitter Authentication

# Authenticate Twitter account
cd agent
bun run auth:twitter

# Follow the OAuth flow in your browser
# Tokens will be stored in agent/plugins/twitter/tokens/

6. Telegram Bot Setup

1. Create bot via @BotFather

2. Get bot token

3. Add token to .env

4. Set webhook (optional) or use polling

Running the Project

Development Mode

1. Start All Services (Recommended)

# From project root
bun run scripts/start-full-dev-environment.sh

This starts:

• Agent runtime with Twitter plugin

• Website client

• API server

• Logging UI

2. Individual Services

# Agent with Twitter
cd agent
bun run start-twitter.ts

# Website
cd clients/website
bun dev

# API Server
cd clients/bill-api-server
bun run server.ts

# Logging UI
cd clients/logging-ui
bun dev

Testing

# Run all tests
bun test

# Test specific components
bun run agent/tests/runtime.test.ts
bun run agent/plugins/twitter/tests/TwitterContextManager.test.ts
bun run agent/tests/event-driven-posting-test.ts

# Test tools
bun run agent/test-web-search.ts
bun run agent/test-workflow.ts

Project Structure

bill-agent/
├── agent/                    # Core agent runtime
│   ├── src/                  # Runtime source
│   │   ├── character/        # BILL character system
│   │   ├── services/         # Core services
│   │   ├── tools/            # Agent tools
│   │   └── workflows/        # Workflow configs
│   ├── plugins/              # Platform plugins
│   │   ├── twitter/          # Twitter integration
│   │   └── telegram/         # Telegram bot
│   └── services/             # LLM services
├── clients/                  # Client applications
│   ├── website/              # Next.js website
│   ├── bill-api-server/      # WebSocket API
│   └── logging-ui/           # Debug interface
└── docs/                     # Documentation

Common Development Tasks

Adding a New Tool

1. Create tool in agent/src/tools/

2. Implement Tool interface

3. Register in runtime.ts

// Example: my-tool.ts
export class MyTool implements Tool {
  name = "my_tool";
  spec = { /* OpenAI function spec */ };
  
  async execute(args: any): Promise<ToolResult> {
    // Implementation
  }
}

// Register in runtime.ts
this.toolManager.registerTool(new MyTool());

Creating a Workflow

1. Create workflow in agent/src/workflows/

2. Export configuration

export const myWorkflow: AgentWorkflowConfig = {
  id: 'my-workflow',
  name: 'My Workflow',
  pipeline: {
    planning: { enabled: true, model: LLM.GEMINI_2_5_FLASH },
    main: { model: LLM.CLAUDE_4_SONNET }
  }
};

Testing Context Pipeline

# Enable immediate context fetch for testing
TWITTER_IMMEDIATE_FETCH_CONTEXT=true bun run agent/start-twitter.ts

# Check timeline monitoring
bun run agent/plugins/twitter/scripts/check-image-analysis.ts

# Test context generation
bun run agent/plugins/twitter/tests/context-integration.test.ts

Troubleshooting

Common Issues

1. "Cannot find module" errors

• Make sure you're using bun not npm

• Run bun install in the specific directory

2. Database connection errors

• Verify Supabase credentials in .env

• Check if tables are created

• Ensure service role key is set if needed

3. Twitter authentication fails

• Verify OAuth credentials

• Check redirect URI matches configuration

• Clear tokens and re-authenticate: bun run agent/plugins/twitter/auth/clear-auth.ts

4. LLM errors

• Verify API keys are set

• Check rate limits

• Enable fallbacks: LLM_FALLBACKS_ENABLED=true

5. WebSocket connection issues

• Check if API server is running

• Verify WebSocket URLs in .env

• Check for CORS issues

Debug Commands

# Check environment
bun run -e "console.log(process.env)"

# Test database connection
bun run -e "
import { createClient } from '@supabase/supabase-js';
const supabase = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SECRET_KEY);
const { data, error } = await supabase.from('timeline_tweets').select('count');
console.log(error ? 'Failed' : 'Connected');
"

# Clear cache
bun run scripts/clear-runtime-cache.ts

Production Deployment

Railway (API Server)

1. Connect GitHub repo

2. Set environment variables

3. Deploy with bun install && bun run server.ts

Vercel (Website)

1. Import project

2. Set environment variables

3. Deploy with automatic builds

Database

1. Use Supabase cloud instance

2. Enable row-level security

3. Set up backups

Additional Resources

• Agent Architecture

• Twitter Plugin Guide

• Character System

• Workflow Documentation

Support

For issues or questions:

1. Check existing documentation

2. Review test files for examples

3. Check GitHub issues

4. Contact the development team