Metadata-Version: 2.4
Name: kanflow
Version: 1.0.0
Summary: A beautiful terminal kanban board built with OpenTUI React
Author: yashwanthbogam
License: MIT
Keywords: kanban,tui,terminal,cli
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# ◈ KanFlow

A beautiful terminal kanban board built with [OpenTUI](https://opentui.com) 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](https://bun.sh))

```bash
bun install -g kanflow
kanflow
```

### curl (auto-adds to PATH, reloads shell)

```bash
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

```bash
pip install kanflow
```

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

### Homebrew

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

### From source (local development)

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

Or run directly:

```bash
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

```json
{
  "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

```bash
# 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](https://bun.sh) >= 1.3.0
- A modern terminal with true-color support

## Tech Stack

- [OpenTUI](https://opentui.com) — native terminal UI core (Zig + TypeScript)
- [@opentui/react](https://www.npmjs.com/package/@opentui/react) — React reconciler for OpenTUI
- React 19

## License

MIT
