claude-blackboard

KO | EN

gitlite — search

#javascript #python #typescript #llm #android #macos #java #windows #awesome #cli #vue #security #ios #open-source

claude-blackboard

(★ 11)

An opinionated Claude Code plugin to improve any project workflow using blackboard AI

claude-blackboard 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Blackboard Plugin for Claude Code

A local SQLite-based "blackboard" for sharing context between Claude Code sessions and subagents. Rather than maximum concurrnecy, the goal is session-independence for agentic coding. Never cling to a context window or terminal tab because the context is already saved. This opens up the ability to move between interactive hands-on work and autonomous containerized workers.

## What It Does

Creates a persistent database that stores:
- **Threads**: Lightweight changesets that model context
- **Plans**: Captured when exiting plan mode (part of a thread)
- **Steps**: Parsed from TodoWrite tool usage (or manually managed)
- **Breadcrumbs**: Progress records from subagents
- **Reflections**: Session insights and learnings
- **Corrections**: Recorded mistakes and their solutions
- **Bug Reports**: Blocking issues with reproduction steps

## Installation

### Option 1: Install from GitHub (Recommended)

```bash
# In Claude Code, add the marketplace
/plugin marketplace add bfollington/claude-blackboard

# Install the plugin
/plugin install blackboard@bfollington
```

### Option 2: Install from Local Directory

```bash
# Clone the repo
git clone https://github.com/bfollington/claude-blackboard.git

# In Claude Code, add as local marketplace
/plugin marketplace add ./claude-blackboard

# Install
/plugin install blackboard@claude-blackboard
```

### Prerequisites

- **Deno 2.x** (required for the blackboard CLI)
  ```bash
  # Install Deno if not already installed
  curl -fsSL https://deno.land/install.sh | sh
  ```
- Ensure `~/.deno/bin` is in your PATH:
  ```bash
  export PATH="$HOME/.deno/bin:$PATH"
  ```

### CLI Installation

If you launch `claude` and run `/blackboard:install` claude will attempt to guide you through the setup process.

After installing the plugin, you need to install the `blackboard` CLI command:

```bash
# Navigate to the plugin directory (usually in ~/.claude/plugins/)
cd ~/.claude/plugins/cache/claude-blackboard/<version>/blackboard/cli

# Install the CLI globally
deno task install
```

This installs the `blackboard` command to `~/.deno/bin`, making it available globally with a single `Bash(blackboard:*)` permission in Claude Code.

## How It Works

### Automatic Initialization

The plugin automatically creates `.claude/blackboard.db` (and `.db-shm` and `.db-wal` files) in your project on session start. The database is project-specific and should be gitignored.

The blackboard CLI provides all functionality through a unified command with subcommands for both interactive use and hook handlers.

### Workflow (Claude)

1. **Planning**: Enter plan mode (Shift+Tab twice), describe what you want to build. When you approve and Claude calls `ExitPlanMode`:
   - The plan is stored in the blackboard
   - Orchestration instructions are injected

2. **Step Creation**: Claude breaks the plan into steps using `TodoWrite`. Each todo becomes a tracked `plan_step`.

3. **Staged Execution**: Claude spawns subagents (using the `implementer` agent) to work on steps. Each subagent:
   - Queries the database for context
   - Implements its assigned step(s)
   - Records a breadcrumb before returning
  
3.a. At any stage, end the session etc. and you can resume it safely - plans and todos are automatically captured in the DB.

4. **Completion**: When all steps are done, run `/reflect` to capture learnings.

### Workflow (CLI)

You can perform any operations Claude would manually using the `blackboard` CLI.

###  Workflow (TUI)

Create threads and next-ups visually, edit plans in your system editor and kick off containerized workers.

## Customizing Worker Images

Blackboard workers run inside Docker containers. By default, they use the plugin's base Dockerfile, but you can customize the worker environment for your project's specific needs.

### Creating a Project-Specific Worker Image

To add project-specific dependencies (language runtimes, packages, build tools):

1. Generate a template Dockerfile:
   ```bash
   blackboard init-worker
   ```

2. Edit `Dockerfile.worker` in your project root to add your dependencies. The template includes examples for Python, Rust, Go, and Node.js projects.

3. Build and spawn workers with your custom image:
   ```bash
   blackboard spawn my-thread --build
   ```

### Dockerfile Lookup Priority

When you run `blackboard spawn --build` or `blackboard farm --build`, the CLI looks for a Dockerfile in this order:

1. `Dockerfile.worker` (project root) - Your project-specific customizations
2. `blackboard/docker/Dockerfile` (plugin directory) - The default base image

If neither exists, you'll be prompted to run `blackboard init-worker`.

### What Must Stay in the Dockerfile

Your custom Dockerfile must preserve these essentials:

- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)
- Deno + blackboard CLI installation
- Non-root `worker` user (Claude CLI security requirement)
- The entrypoint script
- Environment variables: `CLAUDE_PROJECT_DIR=/app/work` and `CLAUDE_PLUGIN_ROOT=/app`

The template generated by `blackboard init-worker` includes all of these with clearly marked sections for your additions.

## Commands

| Command | Description |
|---------|-------------|
| `/crumb` | Record a breadcrumb (progress marker) |
| `/reflect` | Capture a reflection on the session |
| `/oops` | Record a mistake and its resolution |
| `/bug-report` | File a blocking bug with repro steps |
| `/status` | Show current blackboard state |
| `/query` | Run ad-hoc SQL against the database |

## Plugin Structure

```
blackboard/
├── .claude-plugin/
│   └── marketplace.json     # Marketplace manifest
├── commands/                 # Slash commands
│   ├── crumb.md
│   ├── reflect.md
│   ├── oops.md
│   ├── bug-report.md
│   ├── status.md
│   └── query.md
├── agents/
│   └── implementer.md       # Subagent for staged execution
├── hooks/
│   └── hooks.json           # Hook configuration
├── scripts/
│   └── check-cli.sh         # CLI installation check
├── schema.sql
└── README.md

├── cli/                      # Deno-based CLI (replaces bash scripts)
│   ├── deno.json
│   ├── mod.ts               # Entry point
│   └── src/
│       ├── cli.ts           # Command tree
│       ├── commands/        # Interactive commands
│       ├── hooks/           # Hook handlers
│       ├── db/              # Database layer
│       ├── output/          # Output formatting
│       ├── types/           # TypeScript types
│       └── utils/           # Utilities
```

## Database Schema

### Tables

- `plans` - Stored plans with status tracking
- `plan_steps` - Individual steps broken down from plans
- `breadcrumbs` - Progress markers from subagents
- `reflections` - Session insights
- `corrections` - Recorded mistakes and fixes
- `bug_reports` - Blocking issues

### Views

- `active_plan` - Current active/in-progress plan
- `pending_steps` - Steps not yet completed
- `recent_crumbs` - Last 10 breadcrumbs with context

## Troubleshooting

### Plugin not loading

1. Check it's installed: `/plugin`
2. Run Claude Code with `--debug` to see loading details

### CLI not installed

If you see errors about the `blackboard` command not being found:

1. Install Deno 2.x: `curl -fsSL https://deno.land/install.sh | sh`
2. Add `~/.deno/bin` to your PATH
3. Install the CLI:
   ```bash
   cd ~/.claude/plugins/bfollington-claude-blackboard/blackboard/cli
   deno task install
   ```
4. Verify installation: `blackboard --version`

### Database not created

The database is created automatically on session start. To manually initialize:
```bash
blackboard hook init-db
```

### Hooks not firing

1. Verify hooks in `/hooks`
2. Run with `--debug` to see hook execution
3. Ensure the `blackboard` CLI is installed and in PATH

## Development

### Modifying the Plugin

1. Make changes to files in `blackboard/` directory
2. Uninstall: `/plugin uninstall blackboard@marketplace-name`
3. Reinstall: `/plugin install blackboard@marketplace-name`

### Developing the CLI

The CLI is written in TypeScript using Deno. To work on it:

```bash
cd blackboard/cli

# Run in development mode with watch
deno task dev status

# Install your local changes globally
deno task install

# Run tests (if available)
deno test

# Format code
deno fmt

# Lint code
deno lint
```

The CLI uses:
- **@cliffy/command** for the command-line interface
- **@db/sqlite** for native SQLite access via FFI
- Prepared statements to prevent SQL injection
- TypeScript for type safety

claude-blackboard

claude-blackboard 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

claude-blackboard

claude-blackboard 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README