TUI

mikan tui opens a keyboard-first board over the same .mikan/ Markdown files used by the CLI and MCP server.

mikan tui

Board-first flow

The main page is the Kanban board. Statuses render as Columns, Issues render as dense one-line Cards, and archived Issues stay hidden unless explicitly included by other commands.

Key bindings:

Key	Action
h / l or ←/→	Move across Status Columns
j / k or ↑/↓	Move through Cards
H / L	Move the selected Issue to the adjacent Status
Enter	Open the selected Issue detail page
n	Append a Note in a modal prompt
e	Edit Labels in a modal prompt
f	Filter Cards by primary Repository (workspace mode)
a	Confirm Archive in a modal prompt
g	Create or update a GitHub Mirror for the selected Issue
w	Show warning details in a modal
r	Reload from disk
?	Show key help
Esc	Back or cancel
q	Quit

Detail page

Press Enter on a Card to open full-page Markdown detail. The title and metadata stay fixed while the Markdown body scrolls. In detail mode, left/right Column navigation is ignored so the board selection does not change underneath.

If an Issue has frontmatter metadata, Detail shows it as compact JSON in the fixed metadata area. Dense Board Cards intentionally do not show Issue Metadata; they stay focused on Issue ID, title, labels, and dependency hints.

Column count

mikan tui --columns <auto|2|3|4|5> controls how many Status Columns are visible at once.

mikan tui --columns auto   # default
mikan tui --columns 2
mikan tui --columns 3
mikan tui --columns 4
mikan tui --columns 5
mikan tui -c 5

auto derives between 2 and 5 visible Columns from terminal width. Fixed values pin an explicit visible count. This option changes only the TUI viewport; it does not change configured Statuses or Issue files.

Workspace Repositories

In workspace mode (config has a top-level repositories list), each Card shows its primary Repository so the All repositories view stays readable, and Detail shows the primary repository plus any affects Repositories.

Press f to open the Repository filter modal. It lists All repositories plus each configured Repository, and filters the visible Cards by primary repository only. It does not filter by affects, and it never edits Issue files — it only narrows the viewport. Editing repository or affects is not available from the TUI in the initial workspace slice; use the CLI or MCP for that.

Local mutations

The TUI performs the same small mutations exposed by the CLI:

• Move selected Issue to a neighboring Status.
• Append a Note.
• Edit Labels by checking and unchecking config-defined Labels while preserving read-only unknown Labels.
• Archive with confirmation.
• Create or update a one-way GitHub Mirror with g.
• Reload from disk after external edits.

mikan writes through the same project-local lock used by the CLI and MCP server.

Notes

Press n to append a free-form Note to the selected Issue. The Note modal accepts multi-line Markdown: Enter inserts a newline, Ctrl+S saves, and Esc cancels. Empty saves stay in the modal and show Note cannot be empty.

The Note input uses OpenTUI's native textarea for multiline editing, cursor movement, paste handling, wrapping, and a small visible input area. On save, mikan reads the textarea's plain text, trims only leading/trailing blank space, and appends the body to ## Notes through the same mutation path used by CLI and MCP.

GitHub Mirror

Press g on the selected Issue in Board or Detail mode. If the Issue is already mirrored, mikan updates it immediately. If it has no github_issue, mikan opens a confirmation modal showing the Issue ID, title, configured GitHub repo, and a note that local Markdown remains the source of truth.

Mirrored Issues show GitHub #123 in Detail metadata. See GitHub Mirror for setup and rules.

Warnings

The board can show warnings for malformed Issues, duplicate IDs, dependency problems, and hook failures. Press w to open warning details in a focused modal, and press Esc to close it. Warnings are informational; the Markdown files remain the source of truth.