OpenKanban

OpenKanban

**Generated:** 2026-01-03 | **Commit:** 6418109 | **Branch:** main

TUI kanban board for orchestrating AI coding agents. Go 1.25+, Bubbletea, Lipgloss.

Structure

openkanban/
├── cmd/               # CLI (Cobra) - root, new, list, delete
├── internal/
│   ├── ui/            # Bubbletea model/view (HEART OF APP)
│   ├── project/       # Project registry, ticket stores
│   ├── agent/         # Agent config, status detection
│   ├── terminal/      # PTY panes (creack/pty + vt10x)
│   ├── git/           # Worktree management
│   ├── config/        # Config loading/validation
│   ├── board/         # Ticket/Column types
│   ├── app/           # App orchestration
│   └── testutil/      # Test helpers (TestEnv, assertions)
├── docs/              # Design docs
└── main.go            # Entry point

Where to Look

Task	Location	Notes
Add keybinding	internal/ui/model.go → handleNormalMode()	Follow existing switch pattern
New UI mode	internal/ui/model.go → Mode const + handler	Add to Mode enum, create handler
Ticket fields	internal/board/board.go → Ticket struct	Update JSON tags, add to form
Agent config	internal/config/config.go → AgentConfig	Add defaults in defaultAgents()
Git operations	internal/git/worktree.go	Uses exec.Command, not go-git
PTY rendering	internal/terminal/pane.go → View()	vt10x cell-by-cell rendering
Status detection	internal/agent/status.go	Polls OpenCode API/files

Code Map

Symbol	Type	Location	Role
Model	struct	ui/model.go:61	Main app state, Bubbletea model
Update()	method	ui/model.go:250	Event handler (NEVER BLOCK)
View()	method	ui/view.go:13	All rendering
Ticket	struct	board/board.go:69	Task unit with worktree/agent
GlobalTicketStore	struct	project/tickets.go	Multi-project ticket aggregation
Pane	struct	terminal/pane.go:21	PTY-based embedded terminal
StatusDetector	struct	agent/status.go	Agent status polling
WorktreeManager	struct	git/worktree.go:13	Git worktree CRUD
Config	struct	config/config.go:106	Global config with agents map
TestEnv	struct	testutil/testutil.go:14	Isolated test environment helper

Conventions

undefined

Anti-Patterns (THIS PROJECT)

undefined

Unique St