# 🐝 BusyBee

Autonomous TDD coding agent with pause/resume capabilities. A Claude Code plugin that implements features from specifications using test-driven development.

## Overview

BusyBee is an MCP server that converts your specifications into a comprehensive feature list and autonomously implements each feature using TDD. It supports:

- **Multi-modal inputs**: Files, text, images, URLs
- **Pause/Resume**: Stop and continue work across sessions
- **Live status**: Real-time progress monitoring
- **Web dashboard**: Visual interface with state explorer
- **Git integration**: Automatic commits after each feature

## Installation

### As a Claude Code Plugin

```bash
# Add from GitHub
/plugin install nonibytes/busy

# Or add from local path
/plugin install ./path/to/busy
```

### Manual Setup

```bash
# Clone the repository
git clone https://github.com/nonibytes/busy.git
cd busy

# Install dependencies
pip install -e ".[dev]"

# Set OAuth token (required)
export CLAUDE_CODE_OAUTH_TOKEN="sk-ant-oat01-..."
```

## Quick Start

### 1. Initialize a Project

```bash
# From a spec file
/busybee:init spec.md

# From text instructions
/busybee:init "Build a todo app with user authentication"

# From multiple inputs
/busybee:init requirements.txt mockup.png "Add dark mode"
```

### 2. Start Autonomous Implementation

```bash
/busybee:run
```

### 3. Monitor Progress

```bash
# Check status
/busybee:status

# Open dashboard
/busybee:dashboard
```

### 4. Pause/Resume

```bash
# Pause gracefully
/busybee:pause

# Resume later
/busybee:resume
```

### 5. Update Requirements

```bash
/busybee:update "Add export to PDF feature"
```

## Commands

| Command | Description |
|---------|-------------|
| `/busybee:init <inputs>` | Initialize project with specifications |
| `/busybee:run` | Start autonomous TDD implementation |
| `/busybee:pause` | Pause work gracefully |
| `/busybee:resume` | Resume from checkpoint |
| `/busybee:status` | Show progress and status |
| `/busybee:update <inputs>` | Update requirements mid-flight |
| `/busybee:dashboard` | Open web dashboard |

## Project Structure

After initialization, BusyBee creates a `.busybee/` directory:

```
project/
├── .busybee/
│   ├── feature_list.json    # Source of truth (committed to git)
│   ├── state.json           # Operational state (gitignored)
│   ├── history.jsonl        # Activity log (gitignored)
│   └── .gitignore
├── ... your app code ...
```

### feature_list.json

The contract defining all features to implement:

```json
[
  {
    "id": 1,
    "category": "core",
    "description": "User can log in with email",
    "steps": ["Navigate to /login", "Enter email", "Click submit"],
    "passes": false
  }
]
```

### state.json

Current operational state (rebuilt on new machine):

```json
{
  "status": "running",
  "current_feature_id": 45,
  "progress": {"completed": 44, "pending": 156, "total": 200}
}
```

### history.jsonl

Append-only activity log:

```jsonl
{"ts":"2025-12-12T10:00:00Z","event":"init","details":"Created 200 features"}
{"ts":"2025-12-12T10:05:00Z","event":"feature_complete","id":1}
```

## Dashboard

The web dashboard provides:

- **Project list**: All registered BusyBee projects
- **Progress view**: Charts and statistics
- **Feature list**: Filterable table of all features
- **Activity log**: Recent events
- **State explorer**: Raw JSON viewer for debugging

Access at `http://localhost:8765` when running.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                      Claude Code CLI                             │
│  (invokes /busybee:init, /busybee:run, etc.)                    │
└────────────────────────────┬────────────────────────────────────┘
                             │ MCP Protocol
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    BusyBee MCP Server                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │ MCP Tools   │  │ Agent Core  │  │ Dashboard   │              │
│  │ (7 tools)   │  │ (SDK loop)  │  │ (FastAPI)   │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│                          │                                       │
│              ┌───────────┴───────────┐                          │
│              │    State Manager      │                          │
│              │   (JSON/JSONL files)  │                          │
│              └───────────────────────┘                          │
└─────────────────────────────────────────────────────────────────┘
```

## Security

BusyBee uses a project-scoped sandbox:

- **Write operations**: Restricted to project directory only
- **Read operations**: Allowed anywhere (for input files, images)
- **Command execution**: Sandboxed within project

## Authentication

BusyBee uses OAuth tokens (not API keys):

```bash
# Generate token
claude setup-token

# Set environment variable
export CLAUDE_CODE_OAUTH_TOKEN="sk-ant-oat01-..."
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/busybee

# Linting
ruff check src/
```

## Based On

This project is inspired by [Anthropic's autonomous-coding demo](https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding) and the blog post [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).

## License

MIT