# PeerBot

**Your favorite founding engineer, now on Slack**

PeerBot runs Claude Code locally, answering your Slack questions and bringing your AI assistant directly into your workspace:

- Local AI assistant for research, code writing, and deployment using your Claude credentials.
- Agent running in CI/CD pipelines (Github Actions) or cloud machines (with VPN) to debug and deploy code.

## How It Works

- **Powered by Claude Code**: Access the best agentic coding assistant
- **Context-Aware**: Knows your services, local files, infrastructure
- **Multi-Persona**: You can create multiple direct-reports / peers (frontend, backend, devops, marketing, hr). The agent automatically routes the question to the most relevant peer.
- **Slack App**: You can control Claude Code from Slack on mobile

## Quick Start

### 1. Install

**Recommended: NPX**
```bash
npx peerbot-ai@latest run slack
```

**Alternative: Global Install**
```bash
npm install -g peerbot-ai
```

**Docker**
```bash
# Note: ANTHROPIC_API_KEY is required for Docker
docker run -it --rm \
  -v $(pwd):/workspace \
  -e SLACK_BOT_TOKEN \
  -e SLACK_APP_TOKEN \
  -e SLACK_SIGNING_SECRET \
  -e ANTHROPIC_API_KEY \
  buremba/peerbot:latest
```


### 2. Initialize Configuration
```bash
# Using npx (recommended)
npx peerbot-ai@latest init --prompt "Create a peerbot.yaml for a web development team"

# Or if globally installed
peerbot init --prompt "Create a peerbot.yaml for a web development team"
```

### 3. Setup Slack Integration
```bash
# Using npx (recommended)
npx peerbot-ai@latest setup slack

# Or if globally installed
peerbot setup slack
```

### 4. Run Your AI Peers
```bash
# Run all peers (npx)
npx peerbot-ai@latest run slack

# Run specific peer (npx)
npx peerbot-ai@latest run slack --peer frontend

# Run multiple peers (npx)
npx peerbot-ai@latest run slack --peer frontend,backend

# If globally installed, you can use:
peerbot run slack --peer frontend
```

## Configuration

PeerBot uses `peerbot.yaml` to define your AI peers and their capabilities:

### Simple Example
```yaml
version: 1
owner: "@buremba"

peers:
  soham:
    user: "@soham"
    context: "You're a everybody's favorite founding engineer at a startup. You help with web development using Slack App, Claude Code, and MCP servers."
    mcps:
      - github
      - filesystem
    # Fallback for simple commands (when no MCP exists)
    programs:
      allow:
        - Bash(git:*)
        - Bash(npm:*)
        - Bash(node:*)
      deny:
        - Bash(rm -rf:*)
        - Bash(sudo:*)
```

### Advanced Multi-Peer Example
```yaml
version: 1
owner: "@buremba"

peers:
  frontend:
    user: "@uibot"
    context: "Senior frontend engineer specializing in React and TypeScript"
    mcps:
      - figma
      - filesystem
    programs:
      allow:
        - Bash(git:*)
        - Bash(npm:*)
        - Bash(yarn:*)
      deny:
        - Bash(docker:*)

  backend:
    user: "@apibot"
    context: "Backend engineer focused on Node.js APIs and databases"
    mcps:
      - database
      - filesystem
    programs:
      allow:
        - Bash(git:*)
        - Bash(npm:*)
        - Bash(docker:*)
        - Bash(psql:*)
      deny:
        - Bash(rm -rf:*)
  # you might need to run this on your cloud inside your VPC, or on a local machine with a VPN
  devops:
    user: "@opsbot"
    context: "DevOps engineer managing infrastructure and deployments"
    mcps:
      - kubernetes
      - terraform
      - aws
    programs:
      allow:
        - Bash(git:*)
        - Bash(docker:*)
        - Bash(kubectl:*)
        - Bash(curl:*)
      deny: []
```

## Development

**Building from Source (For Development)**
```bash
git clone https://github.com/your-org/peerbot.git
cd peerbot
npm install
npm run build

# Run directly
node dist/cli/index.js run slack 

# Or install globally from source
npm link
peerbot run slack 
```

### Local Slack App
- Runs locally and connects to Slack
- Uses Claude Code with your directory and permissions

### Project Context
- `peerbot.yaml` sets up AI peers and their tools
- Each peer has specific skills and access

### Security Model
- Only the owner can use PeerBot
- Permissions are controlled per command
- Peers run in isolated environments
- Data stays local unless you allow otherwise

## Use Cases

### Local Development (Advanced Vibe Coding)
- **Code Reviews**: Upload files for analysis
- **Debugging**: Get help with error messages
- **Architecture**: Discuss system design decisions
- **Documentation**: Generate docs from code

### Cloud Deployment
- **Infrastructure Monitoring**: Check service health
- **Deployment Status**: Track rollout progress
- **Log Analysis**: Investigate issues
- **Resource Usage**: Monitor performance

## Integration with Claude Code

PeerBot extends Claude Code's capabilities:

- **Uses `.claude/settings.json`** for base configuration
- **Adds peer-specific contexts** via `peerbot.yaml`
- **Maps program patterns** to Claude Code permissions
- **Provides safe execution environment** with granular control

Unlike basic Claude Code usage, PeerBot offers:
- Multiple specialized AI personalities
- Team collaboration through shared configuration
- Enhanced security through permission patterns
- Project-aware context injection

### Docker vs Native Execution

**Docker Limitations:**
- Requires `ANTHROPIC_API_KEY` environment variable
- OAuth authentication is not supported in Docker containers
- This is due to Claude Code's OAuth flow requiring browser access ([issue #1736](https://github.com/anthropics/claude-code/issues/1736))

**Native Execution (NPX, Node.js, etc.):**
- Supports both API key and OAuth authentication
- OAuth is used automatically when no API key is provided
- Recommended for production deployments where OAuth is preferred

## Environment Variables

```env
# Slack Configuration (Required)
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_SIGNING_SECRET=your-signing-secret

# Claude Code Configuration
ANTHROPIC_API_KEY=your-api-key  # Required for Docker, optional otherwise (OAuth supported)
CLAUDE_CODE_USE_BEDROCK=1       # For AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1        # For Google Vertex AI

# Development
DEBUG=true
```

## Docker Deployment

> **Note**: Docker requires ANTHROPIC_API_KEY. OAuth authentication only works when running natively.

### Single Peer
```dockerfile
FROM buremba/peerbot:latest
COPY peerbot.yaml /app/
# ANTHROPIC_API_KEY must be provided
CMD ["peerbot", "run", "slack", "--peer", "devops"]
```

### Multi-Peer with Docker Compose
```yaml
version: '3.8'
services:
  frontend-peer:
    image: buremba/peerbot:latest
    command: peerbot run slack --peer frontend
    environment:
      - SLACK_BOT_TOKEN
      - SLACK_APP_TOKEN
      - SLACK_SIGNING_SECRET
      - ANTHROPIC_API_KEY  # Required for Docker
    volumes:
      - ./peerbot.yaml:/app/peerbot.yaml
      - ./:/workspace
    
  backend-peer:
    image: buremba/peerbot:latest
    command: peerbot run slack --peer backend
    environment:
      - SLACK_BOT_TOKEN
      - SLACK_APP_TOKEN
      - SLACK_SIGNING_SECRET
      - ANTHROPIC_API_KEY  # Required for Docker
    volumes:
      - ./peerbot.yaml:/app/peerbot.yaml
      - ./:/workspace
```

## Troubleshooting

### Bot not responding
- Check that your computer is on and connected
- Verify `peerbot.yaml` exists and is valid
- Ensure Slack app permissions are correct

### Permission denied errors
- Review `programs.allow` patterns in your peer config
- Check if command is in `programs.deny` list
- Verify Claude Code permissions mapping

### Multiple peers conflicts
- Ensure each peer has unique `user` names
- Verify MCP server configurations don't overlap.
- Ensure you're using GIT branches and working trees to avoid conflicts.

## Contributing

PeerBot is built for developers who want secure, context-aware AI assistance. Contributions welcome!