feat(nvim): make Core's terminal splits escapable

[Gerrrt]

Follow-up to #316, from real use: once Claude opens, <C-h/j/k/l> don't work and the split looks like it can only be left by quitting Claude.

The cause

A Neovim terminal buffer forwards every keystroke to the program inside it, and both of Core's terminals call startinsert, so you land in terminal mode. Core's navigation is normal-mode only:

{ "<C-h>", "<cmd>TmuxNavigateLeft<cr>", desc = "Window/pane left" },

so those keys never reach Neovim — the program eats them.

<C-\><C-n>, Neovim's one reserved terminal-mode key, was always the way out. But nothing in the config said so: Core shipped no terminal-mode keymaps at all — mode = "t" appeared nowhere under nvim/. The defect was discoverability, not behavior.

Scope grew during review

The PR originally claimed Claude's was the first terminal buffer Core ships and deferred everything else. Review correctly pointed out that's false: the pytest runner (config/autocmds.lua:206-213) already opens one via jobstart(..., { term = true }) and calls startinsert, so it has the identical trap — and since :q needs normal mode, even closing it requires <C-\><C-n> first. It only escaped notice because that split is read-only output you glance at rather than a prompt you sit inside.

Rather than ship a fix for one terminal and a known-identical bug in the other, both now opt into the same rule.

The change

nvim/lua/gerrrt/utils/term.lua (new) owns the rule and, more importantly, the reasoning. Both terminals call it:

Terminal	Where	Label
Claude's split	plugins/claudecode-nvim.lua (TermOpen autocmd)	Claude
pytest split	config/autocmds.lua (inline after jobstart)	test output

cheatsheet.lua documents it as one Terminal buffers card — <C-\><C-n>, <M-h/j/k/l>, i / a — not a copy in each terminal's card. The panel renders every card simultaneously, so a second copy would only be a thing to keep in step.

Why not just widen the navigator's own maps

Adding mode = { "n", "t" } to <C-h/j/k/l> is the obvious fix and it's wrong:

Key	ASCII	What it does at an interactive prompt
<C-h>	8	backspace
<C-j>	10	newline
<C-w>	23	delete word backward

Claiming any of those breaks editing. <M-…> is unclaimed by the TUIs involved, so it carries the maps instead. mini.move owns <A-h/j/k/l> in normal/visual only — a different mode, so no real collision — and the overload reads the same way: "move in that direction".

Scoping

Maps are buffer-local, so a terminal Core didn't open (:terminal, a plugin's own) keeps its keys untouched.

For Claude's buffer, TermOpen also fires for the pytest split and any :terminal, so rather than matching the term:// name — which is what the plugin does internally, and which would also hit a plain shell opened in a directory containing the word "claude" — it asks the plugin:

local ok, terminal = pcall(require, "claudecode.terminal")
if not ok or terminal.get_active_terminal_bufnr() ~= ev.buf then return end

Deferred one tick via vim.schedule, because TermOpen fires during termopen(), before the provider records the new buffer as active. The pytest side needs no such dance — jobstart(term = true) leaves its buffer current.

Verification

make audit — 246 pass, 0 skip, 0 fail. luacheck clean across 98 files.

Exercised headlessly against the real config:

• Driving the actual <leader>tt mapping's callback opens the pytest terminal, which gets exactly <M-h> <M-j> <M-k> <M-l> labelled "Leave test output, window/pane …".
• Claude's split still gets them labelled "Leave Claude, …" after the refactor.
• An unrelated :terminal opened in the same session gets none — proving the scoping, for both paths.
• Each map resolves to <C-\><C-N><Cmd>TmuxNavigate…<CR>, and TmuxNavigateLeft resolves through vim-tmux-navigator's lazy cmd loading.
• The cheatsheet renders the new card without truncation or reflow.

Note on the branch

The branch name is reused per this session's configuration, but #316 is merged — this is restarted from origin/main, not stacked on merged history.

[Copilot]

Pull request overview

Adds discoverable, Claude-specific terminal escape and navigation controls.

Changes:

• Adds buffer-local <M-h/j/k/l> terminal navigation.
• Documents terminal-mode controls in the cheatsheet.
• Updates the Unreleased changelog.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
nvim/lua/gerrrt/plugins/claudecode-nvim.lua	Adds scoped terminal navigation mappings.
nvim/lua/gerrrt/cheatsheet.lua	Documents terminal controls.
CHANGELOG.md	Records the user-visible change.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Gerrrt]

Correct — the claim was false. Fixed in e949a04.

config/autocmds.lua:206-213 opens a genuine terminal buffer, and it even puts you in terminal mode:

vim.cmd("botright split | enew | resize 15")
local jid = vim.fn.jobstart(argv, { cwd = root, term = true })
...
vim.cmd("startinsert") -- so output scrolls live

So not only was Claude's not the first terminal buffer Core ships — the pytest split has the identical gap. <C-h/j/k/l> don't work there either, and since :q needs normal mode, closing it also requires <C-\><C-n> first.

Reworded to state the actual gap and to name the pytest terminal as sharing it:

nothing in the config said so — Core ships no terminal-mode keymaps at all (mode = "t" appears nowhere under nvim/). The pytest runner in config/autocmds.lua already opened a terminal split and shares that gap; it simply never surfaced there, because it is read-only output you glance at and close rather than a prompt you sit inside.

The commit message carried the same error, so it was amended rather than fixed only in the file — /release-notes drafts from Conventional Commits, so a false claim in the body would have propagated into the next release's notes. The PR description is updated too.

Leaving the pytest terminal itself alone here: giving it the same treatment is a real follow-up, but it is a separate change from the Claude integration and shouldn't ride along in this diff.

---

Generated by Claude Code