Claude Cockpit

A kanban task board with an MCP server and web UI, designed for managing tasks with 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)
• jq (for shell hooks) — brew install jq on macOS

Installation

# 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:

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

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):

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

Or manually add to your Claude Code settings:

{
  "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:

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:

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