kanflow 1.0.0

A beautiful terminal kanban board built with OpenTUI React

◈ 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