Skip to content

feat(ftplugin): add Direct mode for continuous key forwarding - #56

Merged
lambdalisue merged 1 commit into
mainfrom
feat/direct-mode
Jul 7, 2026
Merged

lambdalisue merged 1 commit into
mainfrom
feat/direct-mode

Conversation

@lambdalisue

@lambdalisue lambdalisue commented Jul 7, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Add Direct mode: <C-g>i (or <C-g><C-i>) repeats the existing single-key capture (<C-g><C-o>) until <Esc> is pressed, forwarding every key to the tool in between instead of one at a time.
  • <Esc> is never forwarded to the tool while in Direct mode, consistent with the rest of Aibo's keymaps (send ESC via <C-c> instead).
  • While active, a fixed 5-line window with a thick red border and the title "Direct mode" is shown at the top of the console, explaining the mode and how to exit it.
  • If the prompt window is visible, it is hidden for the duration and reopened in the same Normal/Insert state once Direct mode ends.
  • Also links the new per-tool vimdoc help pages (aibo-live-completion.txt, aibo-acp.txt, aibo-claude.txt, aibo-codex.txt) from the README.

Why

Oneshot capture (<C-g><C-o>) sends exactly one key per invocation, which gets tedious for back-to-back interactions like navigating a tool's interactive menu (arrow-key navigation, repeated confirmations, etc.). Direct mode removes the need to re-invoke the prefix for every single keystroke while keeping the same underlying key-resolution/forwarding mechanism, and keeps the "Esc is always Vim's, never the tool's" invariant intact.

Test Plan

  • just check (luacheck + stylua + full test suite, 292 cases) passes
  • Manually verified in a real Neovim session (via tmux): entering Direct mode from both the console and prompt buffers, the red-bordered indicator window appearing/disappearing correctly, prompt hide/restore (including Insert-mode restoration), key forwarding reaching the underlying tool without lag, and <Esc> exiting without being forwarded

Summary by CodeRabbit

  • New Features

    • Added a new Direct mode for interactive input, letting you send keys straight to the terminal until you exit with <Esc>.
    • Introduced a visible Direct mode indicator and updated default key mappings to launch it with <C-g>i / <C-g><C-i>.
  • Documentation

    • Clarified completion behavior for supported tools and updated key mapping docs to cover Direct mode and related <Plug> actions.
  • Tests

    • Added coverage for Direct mode behavior, including key forwarding and prompt window hide/restore handling.

Oneshot capture (<C-g><C-o>) sends exactly one key per invocation, which
gets tedious for back-to-back interactions like navigating a tool's
interactive menu. Direct mode repeats the same capture until <Esc>,
forwarding every key to the tool in between; <Esc> itself is never
forwarded, matching the rest of Aibo's console/prompt keymaps where the
raw Esc key is reserved for Vim and never sent to the tool as a literal
byte.

While active, a fixed 5-line window with a thick red border is shown at
the top of the console explaining the mode and how to exit it. The
prompt window, if visible, is hidden for the duration and reopened in
the same Normal/Insert state afterwards, since it would otherwise
compete for the same space as the indicator.

Also links the new per-tool vimdoc help pages (aibo-live-completion.txt,
aibo-acp.txt, aibo-claude.txt, aibo-codex.txt) from the README, split out
from the completion feature's design doc.
Copilot AI review requested due to automatic review settings July 7, 2026 09:09
@coderabbitai

coderabbitai Bot commented Jul 7, 2026 •

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

This PR adds a new "Direct mode" feature that forwards raw keystrokes from a console/prompt window directly to the underlying terminal tool until <Esc> is pressed. It introduces a direct_mode module, wires <Plug>(aibo-direct) mappings and default keymaps (<C-g>i/<C-g><C-i>), adds indicator highlight groups, tests, and updates README/doc documentation.

Changes

Direct mode feature

Layer / File(s) Summary
Direct mode core implementation
lua/aibo/internal/direct_mode.lua
New module implementing indicator UI, prompt hide/restore, and a loop that captures single keys and forwards them to a tool until <Esc>.
Wiring Plug mappings and highlights
lua/aibo/internal/console_window.lua, lua/aibo/internal/prompt_window.lua
Adds <Plug>(aibo-direct) mappings that invoke direct_mode.enter, exposes ensure_highlights, and defines AiboDirectBorder/AiboDirectTitle highlight groups.
Default keymap registration
ftplugin/aibo-console.lua, ftplugin/aibo-prompt.lua
Registers default <C-g>i / <C-g><C-i> mappings to <Plug>(aibo-direct).
Direct mode tests
tests/internal/test_direct_mode.lua
New MiniTest suite covering key forwarding, <Esc> handling, and prompt hide/restore behavior.
Documentation updates
README.md, doc/aibo.txt
Documents Direct mode, key mapping tables, <Plug> entries, and completion source toggles.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant PromptWindow
  participant DirectMode
  participant Console

  User->>PromptWindow: <C-g>i
  PromptWindow->>DirectMode: enter(console_winid, send_fn)
  DirectMode->>DirectMode: hide_prompt()
  DirectMode->>DirectMode: open_indicator()
  loop until Esc pressed
    User->>DirectMode: keypress
    alt key is Esc
      DirectMode->>DirectMode: exit loop
    else key is not Esc
      DirectMode->>Console: send_fn(resolved key)
    end
  end
  DirectMode->>DirectMode: close_indicator()
  DirectMode->>DirectMode: restore_prompt()
Loading

Possibly related PRs

  • lambdalisue/nvim-aibo#32: Both PRs modify lua/aibo/internal/console_window.lua to rely on aibo.internal.keycode.get_single_keycode() for key-by-key input handling.
  • lambdalisue/nvim-aibo#44: The main PR's Direct mode exports ensure_highlights and adds highlight groups in prompt_window.lua, directly tied to PR #44's highlight system rework in the same module.
  • lambdalisue/nvim-aibo#40: Both PRs modify lua/aibo/internal/prompt_window.lua, extending the same prompt window highlighting/mapping layer.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: adding Direct mode for continuous key forwarding in ftplugin.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/direct-mode

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@lambdalisue
lambdalisue merged commit 0505c2e into main Jul 7, 2026
6 checks passed
@lambdalisue
lambdalisue deleted the feat/direct-mode branch July 7, 2026 09:15

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new “Direct mode” interaction path for Aibo console/prompt buffers, enabling continuous key forwarding to the underlying tool until <Esc> exits, along with a visual overlay and prompt hide/restore behavior.

Changes:

  • Introduces aibo.internal.direct_mode and binds it via <Plug>(aibo-direct) plus default mappings (<C-g>i / <C-g><C-i>) for console and prompt buffers.
  • Adds a top-of-console indicator overlay (thick border + title) and temporarily hides/restores the prompt window while Direct mode runs.
  • Extends documentation (README + :help aibo) and adds a dedicated MiniTest suite for Direct mode behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
tests/internal/test_direct_mode.lua New tests covering Direct mode key forwarding, overlay, and prompt hide/restore.
README.md Documents Direct mode and expands example config snippet.
lua/aibo/internal/prompt_window.lua Adds shared highlight groups for Direct mode overlay and exposes ensure_highlights().
lua/aibo/internal/direct_mode.lua New module implementing the Direct mode loop, overlay, and prompt hide/restore.
lua/aibo/internal/console_window.lua Adds <Plug>(aibo-direct) mapping for console buffers.
ftplugin/aibo-prompt.lua Adds default Direct mode keymaps for prompt buffers.
ftplugin/aibo-console.lua Adds default Direct mode keymaps for console buffers.
doc/aibo.txt Adds vimdoc entries for Direct mode mappings and behavior.

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

Comment on lines +101 to +103
local had_prompt, was_insert = hide_prompt(console_winid)
local indicator_winid = open_indicator(console_winid)
active_indicators[console_winid] = indicator_winid
Comment thread doc/aibo.txt
repeats the same single-key capture used by `<Plug>(aibo-send)`, forwarding
each captured key until <Esc> is pressed. <Esc> is never forwarded to the
tool; use <C-c> from within Direct mode to send ESC instead. While active, a
fixed 5-line window with a thick red border and the title "Direct mode" is
Comment on lines +129 to +131
console.get_info_by_winid = original_get_info
vim.api.nvim_win_close(console_winid, true)
end

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (1)
tests/internal/test_direct_mode.lua (1)

80-131: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover the Insert-state restore path.

This test only opens the prompt with startinsert = false, so it never exercises the branch that should reopen the prompt in Insert mode after Direct mode exits. Please add one case for startinsert = true to lock down that contract.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/internal/test_direct_mode.lua` around lines 80 - 131, The direct mode
test only covers reopening the prompt when it was initially opened with
startinsert = false, so it misses the Insert-state restore path. Update
test_direct_mode.lua around T["enter hides a visible prompt window and reopens
it after exiting"] to add a case that opens prompt.open(..., { startinsert =
true }), enters direct_mode.enter, and verifies the prompt is reopened with
Insert mode preserved after exit. Use the existing prompt.open,
direct_mode.enter, and prompt.get_info_by_console_winid flow to assert the
restored state.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lua/aibo/internal/direct_mode.lua`:
- Line 22: The `<C-c>` hint in `direct_mode.lua` is misleading because the
`keycode.get_single_keycode()` path uses `vim.fn.getchar()` under `pcall`, so
Ctrl-C is handled as an interrupt and exits Direct mode instead of being
forwarded as ESC. Update the user-facing hint near the Direct mode key list, or
add a separate capture path in the Direct mode loop if ESC forwarding is
actually intended; also add a test covering the Ctrl-C behavior in
`keycode.get_single_keycode()`/Direct mode handling.
- Around line 98-130: The prompt cleanup in M.enter is outside the protected
block, so if hide_prompt or open_indicator fails, restore_prompt and indicator
cleanup will never run. Wrap the full enter flow in a protected call and move
the cleanup logic for close_indicator, active_indicators, and restore_prompt
into a guaranteed finally-style path so the console prompt is restored even when
open_indicator or later steps throw.

In `@tests/internal/test_direct_mode.lua`:
- Around line 21-40: Restore the monkeypatches in the direct mode tests by
ensuring the stubbed vim.fn.getchar and any other replaced helpers are always
put back even if direct_mode.enter() or an assertion fails. Update the affected
test blocks in test_direct_mode.lua to use a cleanup/teardown path around the
direct_mode.enter flow so the original implementations and any opened indicator
windows are reliably restored. Keep the fix localized to the repeated test cases
that currently set and reset the stubs inline.

---

Nitpick comments:
In `@tests/internal/test_direct_mode.lua`:
- Around line 80-131: The direct mode test only covers reopening the prompt when
it was initially opened with startinsert = false, so it misses the Insert-state
restore path. Update test_direct_mode.lua around T["enter hides a visible prompt
window and reopens it after exiting"] to add a case that opens prompt.open(...,
{ startinsert = true }), enters direct_mode.enter, and verifies the prompt is
reopened with Insert mode preserved after exit. Use the existing prompt.open,
direct_mode.enter, and prompt.get_info_by_console_winid flow to assert the
restored state.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 943d8893-e359-4f27-907e-6e694b27a777

📥 Commits

Reviewing files that changed from the base of the PR and between ec9ab10 and abd57e2.

📒 Files selected for processing (8)
  • README.md
  • doc/aibo.txt
  • ftplugin/aibo-console.lua
  • ftplugin/aibo-prompt.lua
  • lua/aibo/internal/console_window.lua
  • lua/aibo/internal/direct_mode.lua
  • lua/aibo/internal/prompt_window.lua
  • tests/internal/test_direct_mode.lua

"directly to the tool.",
"",
" <Esc> Exit Direct mode",
" <C-c> Send ESC to the tool",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
fd -a keycode.lua
ast-grep run --pattern 'getchar($$$)' --lang lua lua/aibo/internal/keycode.lua
cat -n lua/aibo/internal/keycode.lua
rg -n 'C-c|pcall' tests/internal/test_direct_mode.lua

Repository: lambdalisue/nvim-aibo

Length of output: 1049


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- lua/aibo/internal/direct_mode.lua ---'
cat -n lua/aibo/internal/direct_mode.lua

echo
echo '--- tests/internal/test_direct_mode.lua ---'
if [ -f tests/internal/test_direct_mode.lua ]; then
  cat -n tests/internal/test_direct_mode.lua
else
  fd -a 'test_direct_mode.lua'
fi

echo
echo '--- search for direct mode / getchar coverage ---'
rg -n 'get_single_keycode|Keyboard interrupt|C-c|<C-c>|getchar|pcall' lua tests -g '!**/.git/**'

Repository: lambdalisue/nvim-aibo

Length of output: 15981


<C-c> doesn’t send ESC here; it exits Direct mode instead. Line 22 is misleading because keycode.get_single_keycode() wraps vim.fn.getchar() in pcall, so a real Ctrl-C is treated as an interrupt and the loop breaks before anything is forwarded. Update the hint or add a dedicated capture path if ESC forwarding is intended. There’s also no test for the Ctrl-C case.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lua/aibo/internal/direct_mode.lua` at line 22, The `<C-c>` hint in
`direct_mode.lua` is misleading because the `keycode.get_single_keycode()` path
uses `vim.fn.getchar()` under `pcall`, so Ctrl-C is handled as an interrupt and
exits Direct mode instead of being forwarded as ESC. Update the user-facing hint
near the Direct mode key list, or add a separate capture path in the Direct mode
loop if ESC forwarding is actually intended; also add a test covering the Ctrl-C
behavior in `keycode.get_single_keycode()`/Direct mode handling.

Comment on lines +98 to +130
function M.enter(console_winid, send_fn)
local keycode = require("aibo.internal.keycode")

local had_prompt, was_insert = hide_prompt(console_winid)
local indicator_winid = open_indicator(console_winid)
active_indicators[console_winid] = indicator_winid
-- Paint the indicator before the first (blocking) getchar() call.
vim.cmd("redraw")

local ok, err = pcall(function()
while true do
local key = keycode.get_single_keycode()
if not key or key == "<Esc>" then
break
end
send_fn(key)
-- The tool's terminal echo of what was just sent arrives
-- asynchronously; give it a moment to land, then repaint, otherwise
-- it visibly lags by one keystroke behind what was actually typed.
vim.wait(50)
vim.cmd("redraw!")
end
end)

close_indicator(indicator_winid)
active_indicators[console_winid] = nil
if had_prompt then
restore_prompt(console_winid, was_insert)
end
if not ok then
error(err, 0)
end
end

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Prompt is never restored if open_indicator throws.

hide_prompt (line 101) and open_indicator (line 102) run before the pcall block. If open_indicator raises (e.g. console_winid becomes invalid, nvim_open_win fails on a very constrained layout), the function aborts immediately — restore_prompt is never reached, permanently leaving the user without their prompt window until they manually reopen it.

🛠️ Proposed fix: wrap the whole sequence so cleanup always runs
 function M.enter(console_winid, send_fn)
   local keycode = require("aibo.internal.keycode")

   local had_prompt, was_insert = hide_prompt(console_winid)
-  local indicator_winid = open_indicator(console_winid)
-  active_indicators[console_winid] = indicator_winid
-  -- Paint the indicator before the first (blocking) getchar() call.
-  vim.cmd("redraw")
-
-  local ok, err = pcall(function()
+  local ok, err = pcall(function()
+    local indicator_winid = open_indicator(console_winid)
+    active_indicators[console_winid] = indicator_winid
+    -- Paint the indicator before the first (blocking) getchar() call.
+    vim.cmd("redraw")
+
     while true do
       local key = keycode.get_single_keycode()
       if not key or key == "<Esc>" then
         break
       end
       send_fn(key)
       vim.wait(50)
       vim.cmd("redraw!")
     end
   end)

-  close_indicator(indicator_winid)
+  close_indicator(active_indicators[console_winid])
   active_indicators[console_winid] = nil
   if had_prompt then
     restore_prompt(console_winid, was_insert)
   end
   if not ok then
     error(err, 0)
   end
 end
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
function M.enter(console_winid, send_fn)
local keycode = require("aibo.internal.keycode")
local had_prompt, was_insert = hide_prompt(console_winid)
local indicator_winid = open_indicator(console_winid)
active_indicators[console_winid] = indicator_winid
-- Paint the indicator before the first (blocking) getchar() call.
vim.cmd("redraw")
local ok, err = pcall(function()
while true do
local key = keycode.get_single_keycode()
if not key or key == "<Esc>" then
break
end
send_fn(key)
-- The tool's terminal echo of what was just sent arrives
-- asynchronously; give it a moment to land, then repaint, otherwise
-- it visibly lags by one keystroke behind what was actually typed.
vim.wait(50)
vim.cmd("redraw!")
end
end)
close_indicator(indicator_winid)
active_indicators[console_winid] = nil
if had_prompt then
restore_prompt(console_winid, was_insert)
end
if not ok then
error(err, 0)
end
end
function M.enter(console_winid, send_fn)
local keycode = require("aibo.internal.keycode")
local had_prompt, was_insert = hide_prompt(console_winid)
local ok, err = pcall(function()
local indicator_winid = open_indicator(console_winid)
active_indicators[console_winid] = indicator_winid
-- Paint the indicator before the first (blocking) getchar() call.
vim.cmd("redraw")
while true do
local key = keycode.get_single_keycode()
if not key or key == "<Esc>" then
break
end
send_fn(key)
-- The tool's terminal echo of what was just sent arrives
-- asynchronously; give it a moment to land, then repaint, otherwise
-- it visibly lags by one keystroke behind what was actually typed.
vim.wait(50)
vim.cmd("redraw!")
end
end)
close_indicator(active_indicators[console_winid])
active_indicators[console_winid] = nil
if had_prompt then
restore_prompt(console_winid, was_insert)
end
if not ok then
error(err, 0)
end
end
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lua/aibo/internal/direct_mode.lua` around lines 98 - 130, The prompt cleanup
in M.enter is outside the protected block, so if hide_prompt or open_indicator
fails, restore_prompt and indicator cleanup will never run. Wrap the full enter
flow in a protected call and move the cleanup logic for close_indicator,
active_indicators, and restore_prompt into a guaranteed finally-style path so
the console prompt is restored even when open_indicator or later steps throw.

Comment on lines +21 to +40
local original_getchar = vim.fn.getchar
vim.fn.getchar = function()
calls = calls + 1
if calls == 1 then
local indicator_winid = direct_mode._active_indicators[console_winid]
indicator_seen_open = indicator_winid ~= nil and vim.api.nvim_win_is_valid(indicator_winid)
if indicator_seen_open then
indicator_title = vim.api.nvim_win_get_config(indicator_winid).title[1][1]
end
return string.byte("a")
end
return 27 -- <Esc>
end

local sent = {}
direct_mode.enter(console_winid, function(key)
table.insert(sent, key)
end)

vim.fn.getchar = original_getchar

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Restore the monkeypatches in test cleanup.

These cases only clean up on the happy path. If direct_mode.enter() or an assertion fails, the stubbed getchar/get_info_by_winid and open windows leak into later tests and make the suite flaky. Please wrap the body in a cleanup/teardown path so restoration always runs.

Also applies to: 62-73, 94-129, 146-153

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/internal/test_direct_mode.lua` around lines 21 - 40, Restore the
monkeypatches in the direct mode tests by ensuring the stubbed vim.fn.getchar
and any other replaced helpers are always put back even if direct_mode.enter()
or an assertion fails. Update the affected test blocks in test_direct_mode.lua
to use a cleanup/teardown path around the direct_mode.enter flow so the original
implementations and any opened indicator windows are reliably restored. Keep the
fix localized to the repeated test cases that currently set and reset the stubs
inline.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants