Kanbee

A keyboard-driven terminal Kanban board with Vim navigation, designed for developers who value efficiency, control, and seamless integration with their development workflow.

Overview

Kanbee is a minimalist, terminal-native Kanban utility engineered for developers who value speed, precision, and local ownership of their workflow. It eliminates the cognitive overhead of web-based project management tools by providing an interface that resides directly within the development environment.

Rather than context-switching to a web browser, Kanbee brings task management into your terminal—where your code already lives. This eliminates friction, reduces cognitive load, and ensures your project's progress is versioned alongside its source code.

Philosophy

Task management should be an extension of the development process, not a departure from it. By leveraging a local-first data model and seamless Git integration, Kanbee ensures that your project's progress is versioned alongside its source code.

The core principles driving Kanbee:

• Velocity First: Remove friction between thought and action. Navigate with vim keybindings, no mouse required.
• Local Ownership: All data stored in your repository as standard JSON. No cloud vendor lock-in.
• Git Native: Your Kanban board follows the same branching and merging logic as your codebase.
• Extensibility: Modular architecture designed for simplicity and integration into custom pipelines.

Features

Terminal-Native Interface

Kanbee provides a high-performance interactive TUI optimized for rapid data entry and manipulation. The interface is built from the ground up to prioritize keyboard efficiency and minimal visual overhead.

Vim-Driven Navigation

All navigation uses standard Vim keybindings. No learning curve if you're already in Neovim or Vim:

• h / l — Move between columns (or arrow keys)
• j / k — Move between cards (or arrow keys)
• Muscle memory carries directly from your editor

Comprehensive Card Management

Create, edit, and manage cards with full feature support:

• Create: Multi-step card creation with title and optional description
• View: Open card detail view with all metadata at a glance
• Edit: Modify title, description, and icons inline
• Move: Slide cards between columns with m (forward) and M (backward)
• Delete: Remove cards with confirmation safeguards
• Metadata: Support for assignees, labels, colors, timestamps, and custom icons

Dynamic Column Management

Fully customize your workflow on the fly:

• Add Columns: Create new workflow stages (A)
• Rename Columns: Update column names as your process evolves (R)
• Delete Columns: Remove columns with automatic card relocation to the first column (X)
• Preserve State: All changes are persisted to your repository

Multiple Interaction Modes

Kanbee provides different modes optimized for different tasks:

Normal Mode

Your primary interface for navigating and managing the board. Supports card operations, column management, and application control.

Detail Mode

Access comprehensive card information and make edits:

• Tab — Navigate between editable fields (title, description, icon)
• i or Return — Enter edit mode for the focused field
• Escape — Exit detail view and return to normal mode

Insert Mode

Direct text editing within card fields:

• Type to modify content
• Return — Save changes
• Escape — Discard changes
• Backspace — Delete characters

Prompt Mode

Interactive input dialogs for card and column creation:

• Type to enter information
• Return — Confirm input
• Escape — Cancel operation
• Backspace — Delete characters

Confirm Mode

Safety verification before destructive operations:

• y — Confirm action
• n or Escape — Cancel action

Data Persistence and Version Control

Kanbee stores all state in ./data/boards.json using standard JSON format. Your Kanban board becomes part of your repository's version history:

• Full Git integration for tracking board evolution
• Complete offline availability—no network dependency
• Data portability with human-readable JSON format
• Distributed team synchronization via git push and git pull

Extensible Architecture

The codebase is organized into focused modules:

• input.ts — Keyboard event parsing and handling
• renderer.ts — Terminal output and screen rendering
• storage.ts — Persistence layer and data management
• theme.ts — Color and appearance customization
• tui.ts — Application state and mode management
• types.ts — TypeScript interface definitions

This modular approach makes it straightforward to extend Kanbee or integrate it into custom development pipelines.

Installation

Prerequisites

• Node.js 14.0 or later
• npm or yarn

Install Globally

npm install -g kanbee

This installs the kanbee command globally, making it available from any directory.

Install Locally

To use Kanbee within a specific project:

npm install --save-dev kanbee
npx kanbee

Usage

Interactive TUI

Launch the full terminal interface:

kanbee

This opens the interactive Kanban board with all features enabled.

Direct Commands

For scripted or non-interactive operations, Kanbee provides a command interface:

# Create a new card
kanbee add "Implement authentication system"

# Move a card to a specific column
kanbee move <card-id> <column-id>

# Display all cards and boards
kanbee list

# Show current board state
kanbee view

# List all available boards
kanbee boards

# Create a new board
kanbee create-board "Project Name"

# Delete a card
kanbee delete <card-id>

# Synchronize with Git
kanbee push

Keyboard Reference

Navigation

| Binding | Action | |---------|--------| | h or <Left> | Move to previous column | | l or <Right> | Move to next column | | j or <Down> | Move to next card | | k or <Up> | Move to previous card |

Card Operations

| Binding | Action | |---------|--------| | n | Create new card (multi-step: title, optional description) | | <Return> | Open selected card in detail view | | d | Delete selected card (requires confirmation) | | m | Move card forward to next column | | M | Move card backward to previous column |

Column Operations

| Binding | Action | |---------|--------| | A | Add new column to board | | R | Rename current column | | X | Delete current column (cards relocate to first column) | | t | Open theme selection menu |

Edit and Navigation (Detail/Insert Modes)

| Binding | Action | |---------|--------| | <Tab> | Cycle between editable fields in detail view | | i or <Return> | Enter insert mode to edit focused field | | <Escape> | Exit current mode (detail or insert) | | <Backspace> | Delete character (insert mode) |

Theme Selection

| Binding | Action | |---------|--------| | j or <Down> | Move to next theme in list | | k or <Up> | Move to previous theme in list | | p | Preview theme with color mode options | | c | Create a new custom theme | | <Return> or <Space> | Apply selected theme | | <Escape> | Cancel theme selection |

Theme Preview Mode

| Binding | Action | |---------|--------| | j or <Down> | Move to next theme | | k or <Up> | Move to previous theme | | h or <Left> | Previous color mode (auto → dark → light) | | l or <Right> | Next color mode (auto → light → dark) | | <Return> | Apply previewed theme and color mode | | <Escape> | Cancel theme preview |

Theme Editor Mode

| Binding | Action | |---------|--------| | j or <Down> | Move to next color component | | k or <Up> | Move to previous color component | | i or <Return> | Edit selected color (hex format) | | <Escape> | Close theme editor |

General

| Binding | Action | |---------|--------| | q | Exit application gracefully | | C-c | Force exit |

Command Line Reference

| Command | Description | |---------|-------------| | kanbee | Launch interactive terminal interface | | kanbee add [title] | Create new card with given title | | kanbee move [id] [column] | Move card to specified column | | kanbee delete [id] | Remove card from board | | kanbee list | Display all cards in formatted table | | kanbee view | Render static snapshot of current board | | kanbee boards | List all available boards | | kanbee create-board [name] | Initialize new board | | kanbee push | Execute Git synchronization |

Data Storage

Location and Format

Board state is stored in ./data/boards.json. The file uses standard JSON format for complete portability and human readability.

Example Structure

{
  "version": "1.0.0",
  "boards": [
    {
      "id": "default",
      "name": "Product Development",
      "columns": [
        {
          "id": "backlog",
          "name": "Backlog",
          "icon": "○",
          "order": 0
        },
        {
          "id": "in-progress",
          "name": "In Progress",
          "icon": "◐",
          "order": 1
        },
        {
          "id": "done",
          "name": "Done",
          "icon": "●",
          "order": 2
        }
      ],
      "cards": [
        {
          "id": "card-001",
          "title": "Implement JWT authentication",
          "description": "Add JWT-based authentication to API endpoints with refresh token support",
          "columnId": "in-progress",
          "icon": "◆",
          "assignee": "[email protected]",
          "labels": [
            {
              "name": "backend",
              "color": "blue"
            }
          ],
          "created": {
            "by": "alice",
            "at": "2024-01-15T10:30:00Z"
          },
          "completed": {
            "by": "alice",
            "at": "2024-01-18T14:45:00Z"
          }
        }
      ],
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "settings": {
    "user": "alice",
    "theme": "default",
    "showIcons": true
  }
}

Git Integration

Since board data lives in your repository as JSON, standard Git workflows apply:

• Branching: Create feature branches with board updates
• Merging: Resolve conflicts manually or via merge strategies
• History: Full audit trail of board evolution
• Synchronization: Distribute board state across teams via git push and git pull

Customization

Themes

Kanbee supports powerful theme customization with multiple built-in themes, custom theme creation, color mode toggling, and color scheme import/export.

Built-in Themes

Access themes at any time by pressing t in normal mode to open the theme selector.

• default — Default theme (Tokyonight-inspired)
• ghostty — Optimized for Ghostty terminal
• iterm2 — Optimized for iTerm2 (Dracula-inspired)
• kitty — Optimized for Kitty terminal
• wezterm — Optimized for WezTerm
• alacritty — Optimized for Alacritty (Catppuccin-inspired)

The application automatically detects your terminal and applies a matching theme on first launch. You can override this selection at any time by pressing t to open the theme menu.

Theme Selection Interface

When in theme selection mode (press t):

• j/k or ↑/↓ — Navigate between available themes
• p — Preview theme with color adjustments
• c — Create a new custom theme based on selected theme
• Return or Space — Apply the selected theme
• Escape — Cancel and return to normal mode

Theme Preview (NEW)

Preview themes before applying them by pressing p in the theme selection menu:

• j/k or ↑/↓ — Navigate between themes
• h/l or ←/→ — Cycle through color modes (auto, light, dark)
• Return — Apply the previewed theme and color mode
• Escape — Cancel preview

The preview displays:

• Theme name and active color mode
• Color palette with visual swatches
• Preview of how colors will appear in the interface

Dark/Light Mode Support (NEW)

Each theme supports three color modes:

• auto — Automatically detect based on terminal background
• dark — Force dark color palette (adjusted for better contrast)
• light — Force light color palette (inverted colors for light terminals)

Toggle color modes during theme preview by pressing h or l.

Custom Theme Creation (NEW)

Create custom themes tailored to your preferences by pressing c in the theme selection menu:

1. Enter a name for your custom theme
2. Select a base theme to inherit colors from
3. Choose a color mode (auto, light, dark)
4. Edit individual colors in the theme editor

The theme editor allows you to:

• Navigate through all 10 color components with j/k
• Edit colors by pressing Return or i
• Enter colors in hex format: #RRGGBB (e.g., #FF5733)
• See live color validation
• Save changes automatically

Per-Component Color Overrides (NEW)

When creating or editing custom themes, override specific color components:

Available color components:

• Primary — Main accent color for highlights
• Secondary — Supporting accent color
• Accent — Highlight and emphasis color
• Muted — Dim/disabled text color
• Border — UI border and separator color
• Card — Card text color
• Highlight — Selection background color
• Background — Main background color
• Header BG — Header background color
• Status BG — Status bar background color

Color Scheme Import/Export (NEW)

Export and share custom themes as JSON files:

Export a theme:

# Custom themes are stored in ~/.kanflow/data.json
# Access via the theme editor and export function

Import a theme:

Create a JSON file with the following structure:

{
  "name": "My Custom Theme",
  "description": "A beautiful custom color scheme",
  "baseTheme": "default",
  "colorMode": "dark",
  "colors": {
    "primary": "#7aa2f7",
    "secondary": "#9ece6a",
    "accent": "#e0af68",
    "muted": "#565f89",
    "border": "#3b4261",
    "card": "#c0caf5",
    "highlight": "#7aa2f7",
    "bg": "#1a1b26",
    "headerBg": "#24283b",
    "statusBg": "#1f2335"
  },
  "overrides": {}
}

Configuring Themes Programmatically

To set a theme in your ~/.kanflow/data.json settings:

{
  "settings": {
    "user": "alice",
    "theme": "alacritty",
    "colorMode": "dark",
    "showIcons": true,
    "customThemes": []
  }
}

Custom themes are automatically persisted in the customThemes array.

Theme Storage

• Built-in themes — Compiled into the application
• Custom themes — Stored in ~/.kanflow/data.json
• Color preferences — Saved with your settings
• Overrides — Applied per-component to any theme

Icons

Customize visual indicators for columns and cards:

• Column icons: ○ ◐ ● ◇ ◈ ◆ ◎ ▣ ⬡ ✦
• Card icons: ◇ ◈ ◆ ● ◎ ▣ ⬡ ✦ ⬢ ◉

You can customize card icons when editing a card in detail mode. Simply edit the icon field and replace it with any single character.

Labels and Colors

Apply colored labels to cards for categorization and visual organization:

• red, orange, yellow, green, blue, purple, pink

Development

Prerequisites

• Node.js 14.0 or later
• TypeScript 5.0 or later

Setup

git clone https://github.com/TheNeovimmer/kanbee.git
cd kanbee
npm install

Build

npm run build

Output is generated in the dist/ directory.

Development Mode

Run TypeScript directly with ts-node:

npm run dev

Project Structure

kanbee/
├── src/
│   ├── index.ts          # Entry point and CLI handler
│   ├── input.ts          # Keyboard event parsing
│   ├── renderer.ts       # Terminal rendering and UI output
│   ├── storage.ts        # Data persistence and retrieval
│   ├── theme.ts          # Color theme definitions
│   ├── tui.ts            # Application state and mode management
│   └── types.ts          # TypeScript type definitions
├── dist/                 # Compiled JavaScript output
├── data/
│   └── boards.json       # Board state file
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions are welcome. Please review the CONTRIBUTING.md file for guidelines on the development workflow, coding standards, and the pull request process.

Code Standards

• Use TypeScript for all source files
• Follow existing code style and conventions
• Ensure all features are properly typed
• Add tests for new functionality where applicable

License

Kanbee is distributed under the MIT License. See the LICENSE file for the full license text and terms.

Support

For bug reports, feature requests, or general questions, please open an issue on the GitHub repository: github.com/TheNeovimmer/kanbee

Maintained by TheNeovimmer