Kanban

Offline-first, native macOS personal project management & customizable Kanban workspace with first-class Model Context Protocol (MCP) agent integration.

What is Kanban?

Kanban is a private, lightweight engineering workspace built natively for macOS.

Most modern project management tools have evolved into heavy cloud web applications burdened by mandatory subscription lock-in, sluggish multi-second page transitions, tracking telemetry, and opaque cloud databases.

Kanban was built with a different philosophy:

• Zero Cloud Lock-in: All tickets, epics, notes, and projects reside locally on your Mac in SQLite (Write-Ahead Logging).

• Sub-100ms Performance: Instant card dragging, live visual query compilation across 5,000+ tickets, and keyboard-first navigation (Cmd + K, Cmd + N, Cmd + </kbd>).

• First-Class AI Agent Co-Working: Native Model Context Protocol (MCP) stdio server allows Claude Desktop, Cursor, and autonomous coding agents to inspect your backlog, plan sprints, and update tickets in real time.

• Deep Relational Tracking: Full Account → Workspace → Project → Epic → Ticket → Subtasks & Dependencies relational hierarchy.

┌────────────────────────────────────────────────────────────────────────────────────────┐
│  Kanban ─ Personal Workspace                              [ 40:00 ⏱️ ]   [ ⌘K Search ] │
├───────────────────┬────────────────────────────────────────────────────────────────────┤
│ 📁 Projects       │  🚀 Project: Core Infrastructure (INFRA)                           │
│   • Infrastructure│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌──────────┐ │
│   • Mobile App    │ │ BACKLOG (3)   │ │ TODO (2)      │ │ IN PROGRESS(1)│ │ DONE (8) │ │
│   • Interview Prep│ ├───────────────┤ ├───────────────┤ ├───────────────┤ ├──────────┤ │
│ 🎯 Epics          │ │ INFRA-10      │ │ INFRA-42      │ │ INFRA-38      │ │ INFRA-1  │ │
│ ⏱️ Focus Timer    │ │ Database WAL  │ │ Optimize query│ │ Wire MCP Stdio│ │ Init App │ │
│ 📝 Scratchpad     │ │   ● Urgent    │ │   ● High      │ │   ● High      │ │   ● Low  │ │
│ ✅ Daily Todos    │ │   [2/2 sub]   │ │   [0/3 sub]   │ │   [1/2 sub]   │ │   [Done] │ │
│ 📦 Archived       │ └───────────────┘ └───────────────┘ └───────────────┘ └──────────┘ │
└───────────────────┴────────────────────────────────────────────────────────────────────┘

Related MCP server: Kanban MCP Server

📸 Visual Showcase

⚡ Key Capabilities

1. Customizable Kanban Board & Relational Tickets

• Human-Readable Prefixed IDs: Tickets automatically inherit their project code (e.g. APP-101, INFRA-42).

• Configurable Workflow Columns: Create, rename, recolor, and reorder custom columns (Backlog, Todo, In Progress, Review, Done) with category bindings.

• WIP Limits & Guardrails: Set Work-In-Progress limits per column with real-time visual warning tags and safe column deletion with ticket reassignment.

• Relational Work Hierarchy: Projects $\rightarrow$ Epics $\rightarrow$ Tickets $\rightarrow$ Subtasks & Dependencies.

• Markdown Slide Drawer: Inspect and edit descriptions in Markdown by default with interactive checkboxes, syntax highlighting, and discussion threads.

2. Focus Session & Deep Work Timer

• Live Header Countdown Pill: Displays active countdown in the native macOS header without cluttering the canvas.

• Deep Work Presets: Quick launch 25 min (Pomodoro), 40 min, 50 min, or custom durations.

• Audio Synthesis & Gentle Alerts: Customizable tones (ping, bell, chime, pop, subtle) with native macOS system alert banners.

3. Sub-100ms Visual Query Engine & Saved Views

• Visual Expression Builder: Query tickets by status, priority, epic, due date, or labels with explicit AND/OR clause composition.

• Parameterized SQL Generation: Compiles visual query ASTs directly to parameterized SQLite queries in sub-100ms.

• Saved Queries: Save frequently used queries to the project sidebar for instant 1-click execution.

4. First-Class Model Context Protocol (MCP) Agent Integration

• Official Specification: Conforms to MCP 2024-11-05 standard over stdio (JSON-RPC 2.0).

• Supported AI Assistants: Works out of the box with Claude Desktop, Cursor IDE, Antigravity, and autonomous agent runners.

• 8 Core Domain Tools: list_tickets, get_ticket, create_ticket, update_ticket, delete_ticket, search_tickets, list_projects, and get_project_summary.

• Real-Time UI Reflection: Database changes executed by external MCP agents reflect in the desktop application within 1 second.

• Read the MCP Integration Guide for complete configuration examples.

5. Eye-Comfort Canvas Gradients & Automatic Appearance Balancing

• Eye-Comfort Tints: Mitigate monitor glare during long coding sessions with customizable tints:

  • Fresh & Light: warm-sand, soft-slate, light-blue, light-green, magenta, aurora-mist, lavender-dusk, sunset-glow.

  • Dark Nocturnes: dark-obsidian, navy-blue, dark-emerald, dark-magenta, deep-indigo.

• Automatic Balancing: Selecting any light tint automatically sets data-theme="light" and high-contrast dark text/borders. Selecting any dark nocturne sets data-theme="dark" with crisp luminous text.

6. Privacy & Data Sovereignty

• 100% Offline-First: Zero tracking, zero telemetry, zero background network calls.

• Multi-Account Isolation: Multiple local user accounts on one machine with strict cryptographic separation.

• Argon2id Password Security: Secure hashing (m=65536, t=3, p=4) with client-side exponential rate limiting.

• 256-Bit Recovery Keys: Offline high-entropy cryptographic recovery keys for password reset without cloud dependencies.

• Portable Backups: Full JSON database backup and restore with SHA-256 checksum verification and Merge/Replace modes.

7. Multi-Tab Navigation & Persistent Webviews

• Workspace Tab System: Switch smoothly between Board, Dedicated Ticket Detail pages, Focus Timer, Epics, Daily Todos, Notes, and Archived Tickets.

• Persistent DOM / Iframe State: Open <WebviewTab> instances remain mounted in the DOM across tab switches (display: none when inactive). YouTube videos, audio playback, documentation forms, and scroll positions persist seamlessly without resetting or reloading.

8. Keyboard-First Efficiency

• Cmd + K: Global Spotlight search and command palette.

• Cmd + N: Quick ticket creation.

• Cmd + </kbd>: Toggle sidebar collapse.

• Esc: Predictable LIFO modal/drawer dismiss stack.

🏗️ Architecture & Technology Stack

kanban/
├── src/                    # Frontend UI (React 19 + TypeScript + Vite)
│   ├── components/         # Board, tickets, drawers, modals, sidebar, search
│   ├── context/            # Scoped React Contexts (Auth, Project, Ticket, Tab, Focus)
│   ├── lib/                # SQLite WAL storage, Query Compiler, MCP server, Auth crypto
│   ├── styles/             # Vanilla CSS design system (theme.css tokens)
│   └── types/              # Strict TypeScript domain interfaces
├── src-tauri/              # Native macOS Desktop Shell (Tauri 2 + Rust)
│   ├── src/                # IPC endpoints: native notifications, finder reveal, window focus
│   ├── Cargo.toml          # Rust dependencies & metadata
│   └── tauri.conf.json     # Overlay titlebar & traffic light geometry
├── scripts/                # Utility scripts: build-dmg.sh, kanban-mcp, update-local-app.sh
├── docs/                   # Architecture specs, design system invariants & MCP guide
└── tests/                  # 39 test suites (208 passing unit, integration & benchmark tests)

🚀 Quick Start

Option A: Install Distributable DMG (macOS)

1. Download the latest .dmg installer from Releases.

2. Open the disk image and drag Kanban into your /Applications folder.

3. Launch Kanban.

Option B: Build from Source

Prerequisites

• macOS: 13.0+ (Apple Silicon or Intel)

• Xcode Command Line Tools:

  xcode-select --install

• Node.js: 20+ (v22 recommended) & npm

• Rust & Cargo (required by Tauri 2 to compile the native macOS application wrapper & DMG):

  # Option 1: Official rustup installer (recommended)
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
  source "$HOME/.cargo/env"
  
  # Option 2: Homebrew
  brew install rust

  Verify that Cargo and rustc are in your $PATH:

  cargo --version
  rustc --version

# 1. Clone the repository
git clone https://github.com/devvvvvX/kanban.git
cd kanban

# 2. Install dependencies
npm install

# 3. Run in browser development mode
npm run dev

# 4. Or run inside the native macOS desktop shell
npm run tauri dev

Building Release Packages

# Compile frontend and standalone MCP server bundle
npm run build

# Hot-deploy in-place to /Applications/Kanban.app (preserves SQLite database & tokens)
./scripts/update-local-app.sh

# Package a signed/unsigned release DMG installer
npm run build:dmg

🤖 Model Context Protocol (MCP) Setup

Connect Claude Desktop or Cursor to Kanban in seconds:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "macos-kanban": {
      "command": "/Applications/Kanban.app/Contents/MacOS/kanban-mcp",
      "args": [],
      "env": {
        "KANBAN_AUTH_TOKEN": "<your-token-from-settings>"
      }
    }
  }
}

Get your auth token in Kanban: Preferences > MCP Agent > Copy Token.
See the full MCP Guide for detailed tool schemas and Cursor configuration.

⌨️ Keyboard Shortcuts Reference

🧪 Automated Testing

Kanban enforces rigorous test suites covering authentication cryptography, relational ticket hierarchies, visual query compilation, MCP stdio communication, and UI design token assertions:

# Run all 39 test suites (208 tests)
npm test

# Run tests in watch mode
npm run test:watch

# Run TypeScript typechecker
npm run typecheck

🤝 Contributing

Contributions, bug reports, and feature suggestions are warmly welcomed! Please read our CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting pull requests.

📄 License

Kanban is open-source software licensed under the MIT License.
Copyright (c) 2026 devvvvvX.