# Boletus 🍄

**Your first AI company** — open-source framework that runs an autonomous AI team via Slack + Claude CLI.

Send a business plan to your CEO agent. It hires a team, delegates tasks, writes code, creates marketing — all autonomously.

## Quickstart

### Prerequisites

- Python 3.11+
- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
- A Slack workspace ([create one free](https://slack.com/create))
- (Optional) Connect services in [claude.ai/settings](https://claude.ai/settings) → Integrations (Gmail, Notion, Figma, etc.) — your AI team will use these automatically

### 1. Install

```bash
pip install boletus
```

### 2. Create a project & connect Slack

```bash
mkdir my-ai-company && cd my-ai-company
boletus init
```

This walks you through connecting Slack:
1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps) → "From a manifest" → paste `slack-app-manifest.json`
2. Paste your App Token (`xapp-...`) and Bot Token (`xoxb-...`)
3. Paste your Slack Member ID

### 3. Start your AI team

```bash
boletus setup
```

The wizard DMs you in Slack, asks about your business, generates the team config, creates channels, and starts everything.

Upload a business plan PDF or describe what you want to build — the AI team takes it from there.

### 4. Watch it work

- `#ceo` — strategy, delegation, progress reports
- `#engineering` — CTO builds the product, hires devs
- `#growth` — CMO runs marketing, hires content writers

Type `help` in any channel for available commands.

## How it works

```
You: "Build a SaaS for restaurant analytics"
        │
        ▼
   ┌─────────┐     ┌────────────┐     ┌──────────┐
   │   CEO   │────>│ Task Board │────>│ Workers  │
   │ (plans) │     │            │<────│(execute) │
   └─────────┘     └────────────┘     └──────────┘
        │                                    │
        ├── hires @cfo, @sales_rep...       │
        └──────── Slack channels ───────────┘
```

1. **CEO** receives your business plan, breaks it into tasks, delegates
2. **CTO** is a tech lead — scaffolds the project, hires @backend_dev, @frontend_dev, @tester, @devops
3. **CMO** is a growth lead — hires @content_writer, @designer, @seo_specialist
4. **Workers** claim tasks, write real code/content, self-verify before reporting
5. **Auto-testing** — after code tasks, test tasks are auto-created
6. **Manager review** — CTO/CMO approve or reject worker output with feedback
7. **Auto-hiring** — agents create new roles on the fly when workload demands it
8. **Self-correction** — workers escalate blockers, fix tasks auto-created

### Dynamic team

Start with 3 agents (CEO, CTO, CMO). They hire more as needed:

```
CEO writes: @sales_rep: Build a list of 50 target companies and start outreach
→ system auto-creates sales_rep agent, starts working

CTO writes: @tester: Write integration tests for the payment API
→ system auto-creates tester agent, assigns first task
```

No manual configuration needed — the team grows organically.

## Slack commands

| Command | What it does |
|---------|-------------|
| `tasks` | What everyone is working on |
| `my tasks` | Tasks for this channel's agent |
| `team` | Who's on the team and their roles |
| `files` | All local files the team created |
| `links` | Notion pages, GitHub repos, designs — all URLs |
| `report` | Ask CEO for a progress report |
| `hire <description>` | Add a new team member |
| `help` | All available commands |

## CLI

```bash
boletus setup       # Slack wizard — creates team + channels + starts bot
boletus run         # Resume where you left off
boletus init        # Manual setup — creates crew.yaml + .env
boletus doctor      # Check prerequisites
boletus validate    # Verify crew.yaml
boletus agents      # List configured agents
boletus tasks       # Show task board
```

## Integrations (27 services)

Three tiers — zero to full setup:

| Tier | Setup | Examples |
|------|-------|----------|
| **Claude.ai Connectors** | Connect once at claude.ai | Gmail, Notion, Figma, Canva, Gamma, Calendar, PostHog, Cloudflare, Miro |
| **CLI tools** | Token in .env | GitHub (`gh`), AWS (`aws`), Stripe (`stripe`), Vercel |
| **Local MCP** | Auto-configured | PostgreSQL, custom servers |

Your agents use whatever services you've connected in your Claude account — no API keys needed for Claude.ai connectors. CLI tools are configured during `boletus setup`.

## Configuration

Everything lives in `crew.yaml` (auto-generated by the setup wizard):

```yaml
name: "My AI Company"

slack:
  app_token: ${SLACK_APP_TOKEN}
  bot_token: ${SLACK_BOT_TOKEN}

owner:
  slack_id: ${OWNER_SLACK_ID}

git:
  author_name: "AI Team"
  author_email: "ai@example.com"
  github_org: "my-org"  # repos created under this org

integrations: [github, gmail, notion, figma, canva]

projects:
  my-app:
    name: "My App"
    codebase: "./my-app"

# Custom MCP servers
# mcp_servers:
#   my-api:
#     command: "npx"
#     args: ["-y", "@my-org/my-mcp-server"]
```

## Safety

- **Circuit breaker** — agents auto-pause after consecutive failures
- **Manager review** — worker output verified before marking complete
- **Auto-test loop** — code tasks automatically get a follow-up test task
- **Escalation** — workers flag blockers, fix tasks auto-created
- **Fuzzy dedup** — prevents re-delegating the same task
- **Stuck task backoff** — exponential backoff prevents planning loops
- **Structured memory** — agents learn from rejections, share knowledge cross-team

## License

MIT
