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

npx peerbot-ai@latest run slack

Alternative: Global Install

npm install -g peerbot-ai

Docker

# 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

# 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

# Using npx (recommended)
npx peerbot-ai@latest setup slack

# Or if globally installed
peerbot setup slack

4. Run Your AI Peers

# 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

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

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)

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)

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

# 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

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

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!