Setting Up Barbossa.dev: Your AI Engineering Team

Barbossa is a team of five AI agents that work on your codebase while you sleep:

Agent	What it does
Discovery	Finds TODOs, missing tests, issues
Product Manager	Proposes features from your docs
Engineer	Picks from backlog, creates PRs
Tech Lead	Reviews PRs, merges or requests changes
Auditor	Monitors system health

Prerequisites

Linux server (Ubuntu 22.04+) or macOS (Intel/Apple Silicon)
Docker
GitHub CLI
Claude authentication (one of):
- Claude Pro/Max subscription (recommended, long-lasting tokens)
- Anthropic API key (pay-as-you-go)

Quick Start

1. Install dependencies

# Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER && newgrp docker

# GitHub CLI
sudo apt install gh -y

# Claude Code CLI
npm install -g @anthropic-ai/claude-code

2. Generate tokens

# GitHub token
gh auth login
gh auth token  # Save this output

# Claude token (recommended for subscriptions)
claude setup-token  # Follow prompts, save the token

# Or use Anthropic API key instead
# Get from: https://console.anthropic.com/settings/keys

3. Install Barbossa

curl -fsSL https://raw.githubusercontent.com/ADWilkinson/barbossa-dev/main/install.sh | bash

The script will prompt for:

GitHub username and repository
GitHub token (from gh auth token)
Claude token or Anthropic API key

4. Start

cd barbossa && docker compose up -d

5. Verify

docker exec barbossa barbossa health

All checks should pass. Barbossa is now running.

Adding More Repositories

Edit config/repositories.json:

{
  "owner": "your-username",
  "repositories": [
    {
      "name": "my-app",
      "url": "https://github.com/your-username/my-app.git"
    },
    {
      "name": "my-api",
      "url": "https://github.com/your-username/my-api.git"
    }
  ]
}

Then restart: docker compose restart

Configuration Options

{
  "owner": "your-username",
  "repositories": [
    {
      "name": "my-app",
      "url": "https://github.com/your-username/my-app.git",
      "package_manager": "pnpm",
      "do_not_touch": [".env*", "prisma/migrations/"]
    }
  ],
  "settings": {
    "tech_lead": { "auto_merge": true }
  }
}

All agents are enabled by default. Common options:

package_manager: npm, yarn, pnpm, or bun (auto-detected if omitted)
do_not_touch: files agents should never modify
auto_merge: PRs merge automatically when approved (default: true)

Linear Integration

To use Linear instead of GitHub Issues, add to your repositories.json:

{
  "issue_tracker": {
    "type": "linear",
    "linear": {
      "team_key": "ENG",
      "backlog_state": "Backlog"
    }
  }
}

Then add LINEAR_API_KEY=lin_api_xxx to your .env file.

Commands

docker exec barbossa barbossa health        # Status
docker exec barbossa barbossa run engineer  # Run agent manually
docker exec barbossa barbossa status        # Activity log
docker compose logs -f                      # Live logs
docker compose pull && docker compose up -d # Update

Troubleshooting

Token issues: Regenerate with gh auth token or claude setup-token, update .env, then docker compose restart

No PRs created: Check for backlog labeled issues, or run docker exec barbossa barbossa run engineer

Container crashing: Check docker compose logs barbossa for config errors

Resources

What's Next

If you're enjoying Barbossa, I've also put together a collection of Claude Code tools: skills, subagents, themes, and MCP servers I use daily. Worth a look if you want to squeeze more out of your setup.