Tutorial

This is a follow-along tour: keep konoma open in a terminal and try each step as you read. Two keys carry you through everything — ? shows help for the current screen, q goes back one level.

The repository ships this tour as an interactive document — samples/tutorial.md — with links you can actually follow and checkboxes you can actually toggle:

git clone https://github.com/LESIM-Co-Ltd/konoma
konoma konoma/samples        # then open tutorial.md

1. Scroll and leave

Open any directory (konoma ~/some/project), select a text file and press Enter. Scroll with j/k (half page: Ctrl-d/Ctrl-u, ends: g/G), then press q to return to the tree. That round trip — full-screen tree ⇄ full-screen preview — is the core of konoma. There are no split panes.

2. Follow links with Tab

Open a Markdown file with links. Press Tab repeatedly: the focus (an inverted block) walks through every link and checkbox in the document. Enter opens the focused link — local paths open inside konoma (and q brings you back), URLs open in your browser.

3. Toggle checkboxes

In a Markdown file with a task list (- [ ] items), Tab onto a checkbox and press Space. The checkbox toggles and the state is written back to the file — verified against the file on disk first, so a concurrently editing agent is never clobbered. R shows the raw source if you want to see the change.

4. Search and copy

/ searches inside any text preview; n/N jump between matches.
In code/text (and raw Markdown), move the caret with h j k l, select with v (characters) or V (lines), copy with y.
Y copies an @path#L12-34 reference — paste it into an AI-agent chat to point at exact lines.
From the tree, y opens a copy menu: name, relative/full path, parent, or an @relative/path reference.

5. The tree is a file manager

/ filters as you type; Esc clears.
Space opens the file menu: create (n), rename (r), delete (d — to the trash, after a confirmation), copy/cut/paste (c/x/p).
. shows dotfiles, s sorts, i shows file info.
m + a letter bookmarks the cursor item (lowercase = this project, uppercase = global); ' opens the bookmark list — press a letter to jump. Both work from previews too, where they act on the file being shown.

6. Git, live

In a git repository: o opens the changes hub (stage with s, commit with c), Enter on a file shows its full-screen diff (s cycles unified/split), l is the log and g the commit graph — try s on a commit there to pin its branch straight along lane 0. Changed files are colored in the tree, and code previews get a change gutter.

7. Watch an AI agent work

The flagship workflow — konoma on the left, a coding agent on the right:

F turns on follow mode: every file the agent changes appears as a diff, automatically — and the diff shows what changed since you pressed F, not the whole uncommitted diff, so edits you made earlier stay out of the way. Press f to switch between that and the full git diff.
Follow is sticky: scrolling and n/N keep following. q stops it.
While a diff is shown, n/N cycle through the files changed in this follow session.
C lists every uncommitted file; y → @ and Y copy references for the conversation.

More depth: Working with an AI agent · Previews · Git · Files & bookmarks · Configuration