# Claude Cockpit

A kanban task board with an MCP server and web UI, designed for managing tasks with [Claude Code](https://docs.anthropic.com/en/docs/claude-code).

Claude agents can pick tasks, claim them, move them across columns, and work through a prioritized backlog — all through MCP tools. A web dashboard lets you drag and drop tasks, view details, and manage the board visually.

## Features

- **Kanban board** with columns: bank, todo, in_progress, testing, done
- **MCP server** — Claude Code can list, create, claim, move, and update tasks
- **Web UI** — drag-and-drop board at `http://localhost:3333` with live WebSocket updates
- **Multi-agent safe** — file-based locking prevents race conditions when multiple agents work concurrently
- **Claude Code plugin** — slash commands (`/board`, `/pick`, `/done`, `/create`) and hooks for automated workflow
- **Snooze app integration** — optional integration with the Snooze task app (calendar import, task sync)
- **Task priorities & categories** — prioritize work and tag tasks by type
- **Image attachments** — attach screenshots and images to tasks
- **AI auto-categorization** — tasks are auto-tagged using Claude when created via MCP

## Prerequisites

- **Node.js** 20+
- **Claude Code** CLI ([install guide](https://docs.anthropic.com/en/docs/claude-code))
- **jq** (for shell hooks) — `brew install jq` on macOS

## Installation

```bash
# Clone the repo
git clone https://github.com/shmuelix/claude-cockpit.git
cd claude-cockpit

# Install dependencies
npm install

# Build
npm run build
```

## Setup

### 1. Environment variables

Copy the example env file and fill in your keys:

```bash
cp .env.example .env
```

Edit `.env`:
- `OPENAI_API_KEY` — required for AI auto-categorization of tasks
- `CALENDAR_FEED_URL` — optional, for Snooze calendar import

### 2. Start the web server

```bash
npm run web
```

This starts the web dashboard at **http://localhost:3333**.

### 3. Configure Claude Code MCP server

Add this to your Claude Code MCP settings (`~/.claude/plugins/claude-cockpit.json` or via `claude mcp add`):

```bash
claude mcp add claude-cockpit -- node /absolute/path/to/claude-cockpit/build/mcp-server.js
```

Or manually add to your Claude Code settings:

```json
{
  "mcpServers": {
    "claude-cockpit": {
      "command": "node",
      "args": ["/absolute/path/to/claude-cockpit/build/mcp-server.js"]
    }
  }
}
```

### 4. Install the Claude Code plugin (optional but recommended)

This gives you slash commands and workflow hooks:

```bash
claude plugin add /absolute/path/to/claude-cockpit/plugin
```

This enables:
- `/board` — show board status
- `/pick` — pick the next task
- `/done` — finish current task and pick next
- `/create` — create a new task
- Auto-continue workflow after completing tasks
- Terminal title updates showing current task

### 5. Snooze app integration (optional)

If you use the Snooze app, copy the example config and fill in your credentials:

```bash
cp snooze-config.example.json snooze-config.json
```

Edit `snooze-config.json` with your Snooze userId and API key.

## Usage

### Web UI

Open **http://localhost:3333** after starting the web server. You can:
- Drag and drop tasks between columns
- Click tasks to view/edit details
- Create new tasks with the + button or press `n`
- Add notes and image attachments
- Filter by category and priority

### With Claude Code

Once the MCP server is configured, Claude Code can manage your board:

```
> /pick          # Pick the next task and start working
> /board         # Show board status
> /done          # Finish current task
> /create Fix the login bug on mobile
```

Claude will automatically:
- Claim tasks before working on them
- Add notes as it works
- Move tasks to testing/done when finished
- Pick the next task automatically

### MCP Tools

Available tools when connected via MCP:
- `list_tasks` — list all tasks grouped by column
- `get_task` — get full task details
- `create_task` — create a new task
- `update_task` — update task fields
- `move_task` — move task between columns
- `claim_task` / `unclaim_task` — claim/release task ownership
- `add_note` — add a note to a task
- `delete_task` — delete a task
- `snooze_*` — Snooze app integration tools (if configured)

## Project Structure

```
claude-cockpit/
├── src/
│   ├── mcp-server.ts    # MCP server (Claude Code interface)
│   ├── web-server.ts    # Express + WebSocket web server
│   ├── store.ts         # Task storage with file-based locking
│   ├── types.ts         # TypeScript types
│   ├── snooze-api.ts    # Snooze app API client
│   └── import-todo.ts   # Import tasks from external sources
├── public/
│   └── index.html       # Web UI (single-page app)
├── plugin/
│   ├── commands/        # Claude Code slash commands
│   ├── hooks/           # Workflow automation hooks
│   └── skills/          # Claude Code skills
├── tasks.json           # Task data (auto-created, gitignored)
├── column-orders.json   # Column sort order (auto-created, gitignored)
└── uploads/             # Image attachments (gitignored)
```

## Data

All task data is stored locally in `tasks.json`. No external database required. The file is created automatically when you first create a task.

## License

MIT