# Bobby - Discord AI Assistant Bot

## Overview

Bobby is a Discord chatbot that helps answer questions about your codebase, file bugs, and translate business requirements into technical requirements. Bobby leverages Claude Code to understand your codebase and provide intelligent responses in a self-hosted, privacy-first environment.

## Core Architecture

### Main Components

- **index.js** - Main Node.js application using Bun runtime
- **Discord.js** - Handles Discord bot interactions and thread management  
- **Claude Code CLI** - Powers AI analysis of codebases with streaming responses
- **GitHub CLI** - Creates issues automatically when bugs are detected
- **Docker Container** - Self-contained environment with all dependencies

### Environment Variables Required

```
DISCORD_TOKEN=your_discord_bot_token
ANTHROPIC_API_KEY=your_anthropic_api_key  
GH_TOKEN=your_github_personal_access_token
GITHUB_REPO=owner/repo-name
ALLOWED_DISCORD_SERVERS=server_id1,server_id2 (optional)
```

### Docker Architecture

- **Base Image**: `oven/bun:latest`
- **Dependencies**: Git, GitHub CLI v2.61.0, Claude Code CLI
- **Working Directory**: `/app`
- **Repository Clone**: `/app/repo` (target repository)
- **Data Storage**: `/app/data` (Claude Code sessions and configs)
- **Entrypoint**: `entrypoint.sh` (handles authentication and setup)

## Thread-Based Session Management

Bobby uses Discord threads for session management with streaming responses:

1. **New Conversations**: Mention Bobby in any channel to create a new thread with a new Claude Code session
2. **Follow-ups**: Simply type in the thread (no need to mention Bobby) to continue the same Claude Code session
3. **Thread Naming**: Threads are automatically named as `Bobby - Title - session-id` where:
   - `Title` is a 3-5 word summary generated by Claude (hidden from user via regex)
   - `session-id` is the Claude Code session identifier
4. **Streaming Responses**: Real-time message streaming with JSON parsing
5. **Auto-Archive**: Threads automatically archive after 24 hours of inactivity

### Session Flow

```
User mentions Bobby → Create thread → Spawn Claude process → Stream JSON responses → Extract session ID → Update thread name
```

## Available Tools & Capabilities

Bobby has access to the following tools through Claude Code:

- **Read, Grep, Glob, LS** - File operations for codebase analysis
- **Bash(gh:*)** - GitHub CLI for issue creation and repository access  
- **Bash(git:*)** - Git commands for repository operations
- **WebFetch, WebSearch** - Web access for additional information

## Important Limitations

Bobby is designed as a **READ-ONLY** assistant:

- ✅ Can analyze, explore, and read your codebase
- ✅ Can create GitHub issues for bugs and improvements  
- ✅ Can provide code recommendations and suggestions
- ✅ Can fetch latest git changes and analyze repository state
- ❌ Cannot modify, edit, or write code files
- ❌ Cannot make commits or push changes

**Enforcement**: The system prompt explicitly instructs Claude to immediately decline any modification requests and offer to create GitHub issues instead.

## System Prompt Configuration

Bobby uses an optimized system prompt with:

- **Role Definition**: Expert code analysis assistant
- **Context Awareness**: Discord environment constraints
- **Session Management**: Thread-based conversation handling
- **Response Format**: Concise, actionable responses with bullet points
- **Thread Title Generation**: `[THREAD_TITLE: <title>]` pattern (filtered from user view)
- **GitHub Integration**: Automatic issue creation for bugs and feature requests

## Streaming Response Processing

Bobby implements real-time response streaming:

1. **Process Spawning**: `claude` CLI with `--output-format stream-json`
2. **JSON Parsing**: Line-by-line JSON object parsing from stdout
3. **Content Filtering**: Removes `[THREAD_TITLE: <title>]` patterns before sending to user
4. **Session Tracking**: Extracts session IDs and thread titles from metadata
5. **Error Handling**: Captures stderr and provides fallback responses

## Security Features

- **Server Whitelist**: `ALLOWED_DISCORD_SERVERS` environment variable controls access
- **Private Bot**: Designed to be run as private Discord application
- **Token Validation**: Validates all required environment variables on startup
- **Container Isolation**: Runs in isolated Docker environment
- **Data Persistence**: Claude Code sessions persist in `/app/data` volume

## Deployment Options

### Docker Hub (Recommended)
```bash
docker run -d --name bobby \
  -e DISCORD_TOKEN=your_token \
  -e ANTHROPIC_API_KEY=your_key \
  -e GH_TOKEN=your_gh_token \
  -e GITHUB_REPO=owner/repo \
  -v bobby-data:/app/data \
  stewart86/bobby:latest
```

### Build from Source
```bash
git clone https://github.com/Stewart86/bobby.git
docker build -t bobby-bot .
docker run -d --name bobby [env vars] bobby-bot
```

## Automated Publishing

GitHub Actions workflow (`docker-publish.yml`) automatically:
- Builds Docker images on commits to main
- Creates versioned releases on git tags
- Publishes to Docker Hub as `stewart86/bobby`
- Syncs README to Docker Hub (with error tolerance)

## Issue Filing Guidelines

When Bobby detects bugs, it follows these guidelines:

1. **Clear title** describing the bug
2. **Detailed description** with technical details
3. **Reproduction steps** when available  
4. **Labels**: "bug,bobby-detected" or "enhancement,bobby-detected"
5. **Attribution**: "Detected by Bobby (Claude Code assistant)"
6. **Response Format**: Always includes issue link and number

## Memory Management

Bobby stores information in Markdown files in the `docs/` directory, organized by topic. The `CLAUDE.md` file serves as an index to these memory files, helping Claude find relevant information during conversations.

## Troubleshooting

### Claude API Authentication Issues

If authentication errors occur (known issue):

1. Access running container: `docker exec -it bobby /bin/sh`
2. Manually authenticate: `claude` (follow prompts)
3. Exit container: `exit`

This typically resolves authentication problems in the Docker environment.

## Performance Characteristics

- **Startup Time**: ~30 seconds (includes repository cloning)
- **Response Time**: Real-time streaming (starts within 2-3 seconds)
- **Memory Usage**: ~100-200MB base + Claude Code processes
- **Storage**: Minimal (repository clone + session data)
- **Network**: Outbound only (Discord, GitHub, Anthropic APIs)