◈ KanFlow

A beautiful terminal kanban board built with OpenTUI React.

Jira-style card editing · Dynamic columns · Terminal-aware theming · Responsive layout · Vim navigation

Features

• Jira-style card detail — open any card to see title + description + icon, Tab between fields, Enter to edit inline
• Multi-step card creation — n prompts for title, then description
• Dynamic columns — add, rename, delete columns. No limit on how many
• Terminal-aware theming — auto-detects Ghostty, iTerm2, Kitty, WezTerm, Alacritty
• Responsive layout — columns resize to fit your terminal width
• Keyboard-first — Vim-style (hjkl) and arrow key navigation
• Persistent storage — board state saved to ~/.kanflow/data.json
• AI agent plugins — Claude Code, OpenCode, Codex, Copilot, Cursor, Windsurf, Kiro can all manage your board
• Modern icons — ◇ ◈ ◆ ● ◎ ▣ ⬡ ✦ ⬢ ◉
• Custom card icons — each card gets a status icon by column (○ ◐ ●), or set your own per card
• Flat card list — clean, borderless card rows with status indicators

Install

npm (requires bun)

bun install -g kanflow
kanflow

curl (auto-adds to PATH, reloads shell)

curl -fsSL https://raw.githubusercontent.com/yashwanthbogam/kanflow/main/install.sh | bash

This will:

1. Install bun if not present
2. Clone the repo to ~/.kanflow/repo
3. Run bun install
4. Create ~/.local/bin/kanflow launcher
5. Auto-add to PATH in .zshrc, .bashrc, .bash_profile, .profile, and fish config.fish
6. Reload your shell — kanflow works immediately

pip

pip install kanflow

Requires bun on your system. The Python package wraps the bun-based TUI.

Homebrew

brew tap yashwanthbogam/kanflow https://github.com/yashwanthbogam/kanflow
brew install kanflow

From source (local development)

git clone https://github.com/yashwanthbogam/kanflow.git
cd kanflow
bun install
bun run start

Or run directly:

bun run src/index.tsx

Keyboard Shortcuts

Navigation

| Key | Action | |---|---| | ← → / h l | Switch columns | | ↑ ↓ / j k | Navigate cards |

Cards (Jira-style)

| Key | Action | |---|---| | Enter / e | Open card detail view | | n | New card (title → description) | | x / Delete | Delete card | | Shift+← Shift+→ | Move card left/right |

In Detail View

| Key | Action | |---|---| | Tab | Cycle between title ↔ description ↔ icon | | Enter | Edit the selected field | | Esc | Close detail / cancel edit |

Column Management

| Key | Action | |---|---| | Shift+A | Add new column | | Shift+R | Rename current column | | Shift+D | Delete current column |

General

| Key | Action | |---|---| | ? | Toggle help overlay | | q / Esc | Quit |

Icon System

Default Status Icons

Each card automatically gets a status icon based on its column position:

| Column Position | Icon | Meaning | |---|---|---| | 1st column | ○ | Uncompleted / Backlog | | 2nd column | ◐ | In Progress | | 3rd column | ● | Completed / Done | | 4th+ columns | ◇ ◈ ◆ ✦ ⬡ … | Rotating icons |

Custom Card Icons

Override any card's icon in the detail view:

1. Press Enter or e to open card detail
2. Press Tab until the ICON field is selected
3. Press Enter to edit
4. Type or paste any icon/emoji and press Enter

Available palette:

○ ◐ ● ◇ ◈ ◆ ✦ ⬡ ⬢ ◉ ★ ☆ ✓ ✗ ⚡ ⚙ ♦ ♠ ▶ ■ □ ▪ ▫ ◘ ◙ ⊕ ⊗ ⊙ ⊛ ⊜

You can also use any Unicode character or emoji.

Terminal Themes

| Terminal | Theme | |---|---| | Ghostty | GitHub Dark — blues and greens | | iTerm2 | Tokyo Night — purples and pinks | | Kitty | Nord — cool blues and muted tones | | WezTerm | Catppuccin — pastels and lavender | | Alacritty / Other | Catppuccin Mocha (default) |

AI Agent Integration

KanFlow includes plugins for all major coding agents. Each agent can read/write ~/.kanflow/data.json to manage cards and columns — just like a user.

Supported Agents

| Agent | Plugin Location | How It Works | |---|---|---| | Claude Code | .claude/commands/kanflow.md | Slash command: /kanflow | | OpenCode | skills/kanflow/SKILL.md | Auto-discovered skill | | Codex | codex/AGENTS.md | Agent instructions | | GitHub Copilot | .github/copilot-instructions.md | Custom instructions | | Cursor | .cursor/rules/kanflow.mdc | Rules with glob matching | | Windsurf | .windsurf/rules/kanflow.md | Cascade rules | | Kiro | .kiro/skills/kanflow/SKILL.md | Kiro skill | | Any AGENTS.md agent | AGENTS.md | Universal standard |

What Agents Can Do

All agents interact with the board by reading/writing ~/.kanflow/data.json:

• Add cards — push { "id": "<timestamp>", "title": "...", "desc": "...", "icon": "..." } into a column's cards array
• Edit cards — find by id, update title, desc, or icon
• Move cards — remove from source column, append to destination
• Delete cards — filter out by id
• Add columns — append { "id": "<slug>", "name": "...", "icon": "◇", "cards": [] } to columns
• Rename columns — find by id, update name
• Delete columns — filter out by id (keep at least one)

Data Format

{
  "columns": [
    {
      "id": "backlog",
      "name": "Backlog",
      "icon": "◇",
      "cards": [
        { "id": "1", "title": "Setup project", "desc": "Initialize repo", "icon": "○" }
      ]
    },
    { "id": "progress", "name": "In Progress", "icon": "◈", "cards": [] },
    { "id": "done", "name": "Done", "icon": "◆", "cards": [] }
  ]
}

• Columns are not limited to 3 — add as many as you need
• Card icon is optional — defaults based on column position
• Card IDs are unique string timestamps
• Column IDs are lowercase slugs

Quick Agent Commands

# Read the board
cat ~/.kanflow/data.json | jq .

# Launch the TUI
kanflow

Data Storage

Board data is persisted at ~/.kanflow/data.json. Delete this file to reset to the default board.

Requirements

• bun >= 1.3.0
• A modern terminal with true-color support

Tech Stack

• OpenTUI — native terminal UI core (Zig + TypeScript)
• @opentui/react — React reconciler for OpenTUI
• React 19

License

MIT