TUI Navigation

Coco's interactive TUI is keyboard-driven and chord-based. Whether you launch it as coco ui or coco log -i, every git surface — history, working tree, diffs, commit compose, branches, tags, stash — is reachable from any other surface through a unified navigation model.

This page is the source of truth for that model. The companion pages Coco UI and Interactive Log TUI cover surface-specific actions and command-line flags; everything navigation-related lives here.

Mental model

• Views are top-level destinations. There are eighteen: history, status, diff, compose, branches, tags, stash, worktrees, pull-request, pull-request-triage, issues, conflicts, reflog, bisect, submodules, remotes, blame, and changelog.
• Chords jump you between views. They start with g, followed by a single key (g h, g s, g d, g c, g b, g t, g z, g w, g p, g P, g i, g x, g r, g B, g M, g n). Chords replace the top of the navigation stack rather than pushing onto it, so jumping laterally between top-level views never grows the stack (0.81.0). Press g for a live which-key menu of these, or g? for the single-key actions in the view you're already in (see View-keys strip).
• The navigation stack remembers how you drilled in. Pressing < or Esc pops back one level. Because chords replace rather than push, g s → g b → g z → g d is still just one level deep — Esc from there returns you to wherever you were before the first chord, not back through gz → gb → gs. Contextual drill-ins (Enter on a commit, e/c into compose — see Contextual transitions) still push, so history → Enter → diff → e → compose → Esc unwinds one hop at a time: compose → diff → history.
• The repo stack (#931) nests the navigation stack one level deeper. Drilling into a submodule pushes a frame; every view inside that frame is scoped to the submodule's working directory, as if you had launched coco ui from there. Esc / < pops the frame when you're at the root of its view stack — and the header shows a coco › vendor/lib ← esc breadcrumb so the level you're on is always visible.
• Selection state survives navigation. The selected commit, selected branch, selected stash, and current compose draft are all preserved when you jump away and come back.
• The chrome adapts. A ›-separated breadcrumb in the header reflects the navigation stack; the footer's right-side global slot stays the same across views; help and palette read the active view to show the right scope.

Views and chords

g g is a separate chord that jumps to the first commit in the active history list — it pre-dates the view chords. g H (uppercase) on a diff view applies the cursored hunk to the index (companion to bare H which applies to the worktree). g T (uppercase) on the history view opens a new-tag prompt rooted at the cursored commit.

One-keystroke workflows (not view-jumps)

A few uppercase keys kick off workflows that span multiple views. These aren't chords; press them once and the workflow takes over.

z is context-routed, not a second binding. z already means "revert the selected file or hunk" on the status and diff views (see Coco UI → Generic) — that behavior is unchanged. Global undo is what z falls through to everywhere else, or on status/diff when nothing is selected to revert. It inspects the reflog tip, describes the last operation in the confirm panel (e.g. "Undo commit (fix: the thing)"), and on y runs the inverse: a checkout entry switches back to the previous branch; everything else (commit, reset, rebase, merge, cherry-pick, revert, pull) runs git reset --hard HEAD@{1}. Refuses to run while another operation (merge/rebase/etc.) is already in progress. This is lazygit's z undo, generalized from Coco's earlier stash-only undo-drop (u on the stash view, still separate and unaffected).

Going back

The stack always has at least one frame (the root view), so pressing < from the root is a no-op rather than an exit. Use q or Ctrl+C to quit.

Contextual transitions

Some keys perform navigation based on what's selected:

Cross-view workflows

Some flows span multiple views — you mark a state on one view and then act on it from a different one. The footer hints adapt to the flow state so the override is always discoverable.

Compare two refs (#779)

Diff any two refs (branches, tags, or commits) without leaving the workstation:

The compare diff is read-only — no per-file cherry-pick or hunk-apply across arbitrary refs (those don't have a sensible mutate-from-here flow). Just scroll with j/k, toggle split mode with d, and back out with <.

While a base is set, the footer adapts on every compare-flow target view:

Branches:  ↑/↓ branches · enter compare · m clear · esc back
Tags:      ↑/↓ tags     · enter compare · m clear · esc back
History:   ↑/↓ move     · enter compare · m clear · esc back

Outside the compare flow, m is unbound on those views except the dedicated PR view (where it triggers merge).

Multi-select and batch operations (#1361)

Batch-act on several branches, stashes, or a run of commits in one confirm instead of repeating a single-item action N times. (0.81.0)

Marks and a range anchor are mutually exclusive per view — starting a range drops any marks, and marking an item drops an active range. They're alternatives (build a set with x, or define a span with v), not layers.

Where it applies:

On a partial batch failure, the attempted set freezes into marks so a retry (once you've fixed whatever refused) targets exactly what failed, not the whole batch again.

v is also the narrow-terminal sidebar peek (see Footer) — an unrelated binding scoped to terminals under ~100 columns. On branches / stash / history at normal width, v means range-anchor; the two never collide because the peek only engages when the layout has actually folded to a single pane.

Bisect (#784)

Bisect support pairs the g B view with a top-bar BISECTING badge so you can't lose the workflow. The TUI picks up an active bisect on its next refresh — start it from your shell with git bisect start <bad-ref> <good-ref> and re-open coco ui.

Inside the bisect view, g and b bypass the chord prefix — pressing g marks good rather than entering chord mode. The path back out is < / Esc (never a chord). Outside the view, g/b/s/x keep their existing semantics.

The status line surfaces git's own "Bisecting: N revisions left to test after this (roughly K steps)" line after each decision so you always know how far you have to go.

Submodule drill-in (#931)

Drilling into a submodule pushes a repo frame that re-scopes every view — history, branches, status, diff, even the inspector — to the submodule's working directory. It's the mental equivalent of running coco ui from inside the submodule, but without leaving the parent session.

The header shows a breadcrumb whenever you're inside a frame:

Frames stack. Drilling further (a submodule of the submodule) produces coco › vendor/lib › vendor/lib/inner ← esc, and each Esc walks back one level.

Cached state survives the round trip — pop back to the parent and you land on the same row, with the same filter, with cached context (no refetch flicker).

Mutations (stage, commit, checkout, …) inside a nested frame run against the submodule's working tree, since the active frame's SimpleGit instance is bound to its workdir. Two known polish items are tracked as follow-ups to #931: per-frame sidebar tab / sort mode persistence (today these carry over root → submodule), and frame-tagging on in-flight refreshes (rare race where a parent refresh that's mid-await when a push fires writes to the submodule frame).

Command palette (:)

The palette is an interactive launcher, not a static reference. Press : to open it; type to filter, press Enter to run.

The palette enumerates every keybinding plus every workflow action (commit, delete-branch, ai-commit-summary, etc.). Recently-used items float to the top when the filter is empty; once a query is set, relevance ranking takes over and recent ordering is ignored.

Behind the scenes, palette execution maps each command id to the same events the keystroke would dispatch — palette and keymap stay in sync.

Search (/)

/ opens filter mode in the active view:

• History: ranked fuzzy matching across hash, date, author, message, and refs. Four prefixes re-run git log server-side instead of filtering the loaded window client-side:
  • path:<spec> — commits touching a path (e.g. path:src/foo).
  • author:<name> — commits by a given author (e.g. author:alice).
  • S:<token> — pickaxe (0.81.0): commits that changed the occurrence count of a literal string (git log -S).
  • G:<regex> — grep-diff (0.81.0): commits whose patch matches a regex (git log -G).
• Branches: substring match on branch names and upstreams.
• Tags: substring match on tag names and subjects.
• Stash: substring match on stash refs and messages.

While filtering, the active view's header shows N/M totals plus the filter text (5/12 local | filter: feat). Ctrl+U clears, Esc or Enter exits filter mode. The four server-side history prefixes re-fetch on Enter; the footer's active-filter indicator shows exactly what ran (e.g. -Sfoo, -Gfoo.*bar) so you can tell a server-side filter from a plain client-side one.

In other views (diff, compose, status), / opens filter mode but the surface doesn't currently apply it — typing closes the filter without effect. That's a polish opportunity for a follow-up; track it via the wiki/issue tracker.

Help overlay (?)

Help is grouped into two sections so the right scope is always obvious:

• Global — bindings that work from any view or focus (?, :, q, r, focus nav, workflow actions, the navigation chords).
• This view (<active>) — bindings filtered to what makes sense in the current view + focus, with the active view named in the section title so you always know which scope applies.

Esc or ? closes the overlay.

View-keys strip (g?)

The g which-key overlay solves discovery for the chords (g h, g s, …). g? is its counterpart for the single keys — the per-view overloads where the same letter means different things in different views (c cherry-picks on history but cherry-picks a file in a commit diff; R reverts on history; m marks a compare base; [/] jump hunks or sidebar tabs depending on focus).

Press g? in any view to pop a compact strip listing exactly the single-key actions available right there, with their labels. It's sourced live from the same binding table the ? help uses, filtered to the active view + focus — so as you move between views the list changes with you, and it can never drift out of sync with what the keys actually do.

• g? — open the strip for the current view.
• ? — step up from the strip to the full categorized help (progressive disclosure).
• Esc — close.

It changes nothing about what any key does; it's a pure discoverability surface. Bare ? still opens the full help directly, so existing muscle memory is untouched. The strip is also reachable from the command palette (:) as keys.

Footer

The footer has two slots that don't overlap:

• Contextual (left, dimmed) — what changes by mode/view/focus, like ↑/↓ files · enter diff · space stage · z revert · e/c compose in status.
• Global (right edge, dimmed) — persistent affordances anchored to the right: g jump · < back · ? help · : cmds · q quit.

In special modes (filter / help open / palette open), the global slot trims down (q quit always present) since : and ? mean close in those contexts.

A few keys are context-routed across surfaces:

• [/] — diff view: jump previous/next hunk or file. Sidebar focused: cycle sidebar tabs. Inspector focused (on short terminals where the inspector is tabbed): cycle inspector tabs. Each context owns its meaning of the key; the footer hints surface which one applies.
• ←/→ — sidebar focused: switch between Status / Branches / Tags / Stashes / Worktrees tabs. Vertical axis (↑/↓) navigates items within the active tab.
• v — narrow / single-pane terminals only (under ~100 cols): momentary sidebar peek from the main or inspector pane. v again or Esc snaps you back to where you were. A no-op in the full three-pane layout where everything's already visible.

Header breadcrumb

The header shows where you are in the navigation stack as a ›-separated trail:

The breadcrumb is purely informational — there's no clickable navigation through it (the TUI is keyboard-only). Use < / Esc to walk it back.

Themes and accessibility

• 108 built-in color themes / 109 selectable presets (29 light) — default, monochrome, catppuccin, gruvbox, dracula, nord, tokyo-night, and many more (full gallery). Set via --theme <preset> or logTui.theme.preset in .coco.config.json. NO_COLOR=1 honored; monochrome for grayscale. The active/selected row renders readably on every theme (light + dark, truecolor + downgraded).
• NO_COLOR=1 is honored end-to-end. Borders fall back to the terminal default and color emphasis is dropped without changing layout.
• The chrome uses a small set of unicode glyphs (›, ↑/↓, ·); layout is ASCII-only so a missing glyph never breaks columns.
• Empty / loading copy is unified across views and points users at the next sensible action — no blank screens.
• The TUI is keyboard-only by design. Every action is reachable from the keymap or : palette. Mouse input is not consumed.

What's new since v0.34.0

The shell architecture landed in v0.34.0 (TUI shell epic, #747). The releases since have layered on a navigable, action-rich workstation. Highlights worth knowing if you came from an earlier version:

v0.81.0 — global undo, multi-select, pickaxe search, confirmation cleanup

• Global undo. z falls through to a reflog-powered undo of the last git operation when nothing more specific claims it — see One-keystroke workflows.
• Multi-select & batch operations. Mark or range-select branches, stashes, and commit spans and act on all of them in one confirm — see Multi-select and batch operations.
• Pickaxe & grep-diff search. New S:<token> and G:<regex> filter prefixes join path:/author: for server-side commit-content search — see the Search (/) section below.
• y is now reserved exclusively for confirming destructive actions, everywhere. The one exception — the worktree-conflict prompt's "switch to that worktree" option — moved to s.
• Two-stage Esc now protects every multi-line input prompt (PR comments, review bodies), matching the filter/palette/theme-picker contract: first Esc clears typed text, second Esc closes.
• g-chords replace the top of the navigation stack instead of pushing — see the updated Mental model above. Esc after any run of chords always returns exactly one level.
• Status-line navigation echoes (e.g. "jumped to ...") now clear on your next keystroke instead of persisting until something else overwrites them.

v0.62.x — workstation readability tweaks

• Worktree-aware checkout conflicts. Checking out a branch that's already checked out in another worktree no longer dead-ends on git's raw already checked out at <path>. Coco names the branch + worktree and offers s (switch to that worktree — opens it as a nested repo frame), r (remove that worktree and check out here — refused/warned if it's dirty), or x (remove the worktree and delete the branch). (0.62.4; the switch key moved from y to s in 0.81.0 — see below — so y means "confirm the dangerous option" everywhere, with no exceptions)
• Stash view is an aligned table. The stash list is now a real table — a dim column header over aligned columns (ref · age · branch · files · message), metadata dim, the message filling the remainder and tail-truncated, numeric columns right-aligned. Rows fit the panel exactly (no wrapping), and on narrow terminals the columns the inspector preview already shows are shed in priority order (branch → age → file count) before the message is squeezed. (0.62.3)
• The checked-out branch is highlighted in green. Its name renders in the theme's success colour (matching the green * HEAD marker) in both the Branches view and the sidebar Branches tab; the colour yields to the selection highlight on the focused row, and NO_COLOR themes fall back to the * glyph. (0.62.3)
• Inline spinner on branch checkout. Checking out a branch now shows the same per-row pending spinner as a delete, instead of blanking the list behind a "loading branches…" placeholder. Deleting a branch that's checked out in another worktree now explains which worktree to free up rather than dead-ending on git's raw error. (0.62.2)
• History opens on the full multi-ref graph again on a bare coco. A bare coco launch was dropping the --all default and booting the history view in compact mode (fewer commits, branches-ahead hidden, a graph that could loop back to the initial commit); it now opens on the all-refs graph as intended. (0.62.1)

v0.60.0 — stash workflow, narrow terminals, honest chrome

• Stash workflow overhaul. The stash list went from ref + message to richer rows: stash@{0} on main · 3 files · 2w <message> (origin branch · file count · relative age; refs are the compact stash@{N} form again). New keys on the stash view / sidebar tab:
  • R rename a stash · b create a branch from it (git stash branch) · A apply restoring the staged/unstaged split (git stash apply --index, vs plain a) · u undo the last drop.
  • gZ stashes all changes from any view (including status / diff / compose, where bare S is the commit-split key) — mnemonic pair with gz (jump to the stash view). Submitting an empty message makes a quick WIP stash. The : palette adds Stash staged only (--staged) and Stash keeping index (--keep-index).
• Narrow terminals are first-class. Below 100 columns the three-pane layout folds to a single full-width pane (the old 8-cell icon rails are retired). Tab / Shift+Tab cycles which pane is visible (sidebar → main → inspector); the footer prepends a tab: [sidebar] main inspector switcher. v momentarily peeks the sidebar from the main/inspector pane — v or Esc snaps you straight back (a no-op in the full three-pane layout).
• Honest, trimmed chrome. The commit-diff footer was relabeled j/k lines · [/] hunk (the keys did the opposite of what it said), and each footer row was trimmed to its highest-value actions (the rest live in ?). The header breadcrumb dropped its trailing ← < hint (it's pure location now), and the ⊘ no PR chip is gone — the PR chip shows only when a PR actually exists.

v0.40.0 — unified three-tier navigation

Wherever a list of items lives inside a named group, the group's title is now a first-class cursor target with its own canonical action. The same mental model carries across all four surfaces it applies to:

• Sidebar. ↑ at items index 0 promotes the cursor onto the active tab's header (Branches / Tags / Stashes / Worktrees). ← / → scans neighboring tab headers; Enter on the header drills into the dedicated view.
• Status view. Files render under ▾ Staged (n) / ▾ Unstaged (n) / ▾ Untracked (n). ← / → jumps between groups; ↑ at a group's first file promotes to the header; Enter on a header fires the batch action (Stage all unstaged, Unstage all staged, Stage all untracked with y-confirm).
• Inspector Actions. [ / ] toggles to the Actions tab; ↑ / ↓ moves the cursor; Enter fires the cursored action (cherry-pick, revert, reset, yank, open in browser).
• Stash diffs. diff --git rows render as compact ▾ <path> headers; the file the cursor is scrolled inside gets selection styling so the active context is always visible.

Header focus persists across ← / → switches in the sidebar so the user can scan tab → tab → drill in one fluid motion. All four surfaces use the same selection styling for their headers, so the visual cue is the same wherever you are.

v0.39.0 — inspector and cross-list cursor sync

• The right-hand inspector dropped its duplicative repo / branch / status trailer and added an Actions: section listing the keystrokes available on the cursored entity. Destructive actions render with a [!] marker.
• Inspector at rest is narrow (~22% of width); focusing it via tab expands to ~40% so the metadata, body preview, and action panel get the room they need. Mirrors the existing sidebar focus-expand pattern.
• On short terminals (rows < 28), the inspector collapses into a tabbed [Inspector] Actions layout. [/] while the inspector is focused cycles tabs.
• Cursoring a branch in the sidebar / branches view auto-jumps the history panel cursor to that branch's tip commit (debounced 150ms). Same for tags. A Synced history to <ref> status confirms the jump even when the dedicated branches view obscures the history graph.
• Current branch always pins to position 0 of the branches list regardless of sort mode. After a checkout, the cursor snaps back to row 0 so it lands on the just-checked-out branch.
• New keys on the history view: B create branch from cursored commit, gT create tag from cursored commit. The prompt itself is the affirmative gate.
• Header label is coco (was coco ui).

v0.38.0 — action surface

• Pull-request panel via g p: header / checks / reviews / body with m / x / a / R / c / O action keys.
• History-view mutations: R revert, Z reset (soft / mixed / hard mode prompt), i interactive rebase. All routed through y-confirm or mode prompt.
• d on a commit-diff or stash-diff toggles between unified and side-by-side rendering. Persists per-repo. Falls back to unified on terminals narrower than 120 cols.
• H on a diff view applies the cursored hunk to the worktree (git apply). gH applies to the index (git apply --cached).
• Higher-fidelity commit graph: pattern junctions (├╮ / ├╯), per-lane coloring, distinct merge / HEAD glyphs (◆ / ◉).
• In-sidebar selection: when sidebar is focused, ←/→ switch tabs and ↑/↓ (or j/k) navigate items. Per-entity ops (Enter checkout / a apply / D delete / etc.) fire from the sidebar without drilling into the dedicated view.
• Multi-line input prompt for PR comments + review bodies. Enter inserts a newline; Ctrl+D submits. Single-line prompts (branch names, merge strategies) keep Enter as submit.
• Branches list polish: dropped "even with X" noise, added relative timestamps (today / Nd / Nw), four-state remote indicator (* / ◌ / ≡ / ↕).
• Stash diff header surfaces @{N} <message> on <branch> instead of the raw timestamp ref.

v0.37.0 — quick-win affordances

• y / Y yank the cursored identifier (commit hash, branch, tag, stash ref, file path) to the system clipboard from every promoted view.
• 1 / 2 / 3 on the status view toggle staged / unstaged / untracked visibility.
• /path:src/foo and /author:alice re-run git log with the matching flags so commits touching a path or by a given author show up without dropping to a shell.

v0.34.0 — chord prefix

g is now a chord prefix. Pressing g alone no longer toggles the graph immediately — it waits for the second key. The graph toggle moved to \. Previously g did toggleGraph as a side effect of starting a gg chord, which caused a brief flicker on every g-prefixed sequence.

If you had muscle memory for g, you can either retrain to \ or use : and search for "graph" to invoke it from the palette.

Quick reference card

1Navigation              Within a view              Modes
2  g h  history            j/k, ↑/↓   move             ?    help (toggles)
3  g s  status             gg / G     top / bottom     :    palette (toggles)
4  g d  diff               n / N      next / prev      /    search (toggles)
5  g c  compose            Tab        focus next       Esc  close mode / back
6  g b  branches           ←/→        sidebar tab      <    back (nav stack)
7  g t  tags               [/]        sidebar tab /    Quit
8  g z  stash                         inspector tab      q, Ctrl+C
9  g w  worktrees          1-5        sidebar jump
10  g p  pull request       \          toggle graph
11  g x  conflicts          r          refresh
12  g r  reflog             d          unified ↔ split  (diff view)
13  g B  bisect             m          mark compare base (branches/tags/history)
14                          g/b/s/x    bisect: good/bad/skip/reset (bisect view)
15
16History view ops          Diff view ops              PR view ops
17  c   cherry-pick           H   apply hunk             m   merge
18  R   revert                gH  apply hunk to           x   close
19  Z   reset (mode prompt)       index                  a   approve
20  i   interactive rebase    [/] file/hunk nav          R   request changes
21  B   create branch here    space  stage/unstage       c   comment
22  gT  create tag here       z   revert                 O   open in browser
23  y/Y yank hash             c   cherry-pick file
24  O   open in browser

For surface-specific actions (staging, hunks, commit compose, workflow keys like D/X/I), see the per-view sections in Coco UI.