feat(tui): add Vim editing mode with runtime /vim toggle

[honjo-hiroaki-gtt]

• Summary: Adds a first‑class Vim editing mode to the TUI composer, with a runtime toggle via /vim. Default remains the standard key bindings when unset.
• Motivation: Implements a frequently requested feature for keyboard‑centric users; related to vi editing mode #2387.
• Changes:
  • Vim mode (Normal/Insert) in the composer:
    • Movement: h/j/k/l, 0/$, b/w/e
    • Insert: i/I/a/A/o/O
    • Edits: x/X/D, dd (delete line), dw/de (delete word)
  • Footer mode label: Shows INSERT/NORMAL; displays (d...) when an operator is pending
  • Runtime toggle: /vim to enable/disable Vim mode without restarting
  • Config: Enable via [tui] editor_keymap = "vim" or CLI -c tui.editor_keymap=vim
  • Input handling: Bypass paste‑burst buffering in Vim Normal for predictable key behavior
• UX Notes:
  • When the composer is empty, Esc primes backtrack (edit‑previous). Use Ctrl+[ to reliably enter Vim Normal, or type any character first then press Esc.
  • Footer reflects the current mode immediately; /vim toggles it at any time.
• Compatibility: No breaking changes; default behavior is unchanged.
• Tests: Adds/updates unit tests covering basic navigation, insert/normal transitions, dd, dw, and de.
• Docs: Updates Getting Started with config example, /vim toggle, and Esc vs Ctrl+[ note.
• How To Test:
  • Unit: cd codex-rs && cargo test -p codex-tui
  • Manual: cargo run -p codex-tui -- -c tui.editor_keymap=vim, then verify Normal/Insert, movement/edit keys, and /vim toggle
• Scope & Risk: TUI‑only; no changes to sandboxing or execution paths. Low risk, isolated to input handling and footer rendering.
• Future Work: Counts/repeat (e.g., 3w/2dd), additional operators (db, cw/ce, yy/p), optional mode indicator placement, persisted toggle state.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[honjo-hiroaki-gtt]

I have read the CLA Document and I hereby sign the CLA

[mertkaradayi]

• Summary: Adds a first‑class Vim editing mode to the TUI composer, with a runtime toggle via /vim. Default remains the standard key bindings when unset.

• Motivation: Implements a frequently requested feature for keyboard‑centric users; related to FR: vi editing mode #2387.

• Changes:

  • Vim mode (Normal/Insert) in the composer:

    • Movement: h/j/k/l, 0/$, b/w/e
    • Insert: i/I/a/A/o/O
    • Edits: x/X/D, dd (delete line), dw/de (delete word)

  • Footer mode label: Shows INSERT/NORMAL; displays (d...) when an operator is pending

  • Runtime toggle: /vim to enable/disable Vim mode without restarting

  • Config: Enable via [tui] editor_keymap = "vim" or CLI -c tui.editor_keymap=vim

  • Input handling: Bypass paste‑burst buffering in Vim Normal for predictable key behavior

• UX Notes:

  • When the composer is empty, Esc primes backtrack (edit‑previous). Use Ctrl+[ to reliably enter Vim Normal, or type any character first then press Esc.
  • Footer reflects the current mode immediately; /vim toggles it at any time.

• Compatibility: No breaking changes; default behavior is unchanged.

• Tests: Adds/updates unit tests covering basic navigation, insert/normal transitions, dd, dw, and de.

• Docs: Updates Getting Started with config example, /vim toggle, and Esc vs Ctrl+[ note.

• How To Test:

  • Unit: cd codex-rs && cargo test -p codex-tui
  • Manual: cargo run -p codex-tui -- -c tui.editor_keymap=vim, then verify Normal/Insert, movement/edit keys, and /vim toggle

• Scope & Risk: TUI‑only; no changes to sandboxing or execution paths. Low risk, isolated to input handling and footer rendering.

• Future Work: Counts/repeat (e.g., 3w/2dd), additional operators (db, cw/ce, yy/p), optional mode indicator placement, persisted toggle state.

I am glad that someone is making it !
Thanks sir ! I was about to get my hands dirty for that lol

[nornagon-openai]

As a long time Vim user who feels most comfortable editing text in Vim, I'm hesitant to add a Vim emulation mode to the prompt textbox. The reason is that I generally find Vim emulations that are not actually Vim frustrate me more than they delight me, as inevitably they do not support some feature which I rely on to feel comfortable in Vim, e.g. ciw or ..

Would it perhaps make sense to instead add a keyboard shortcut to edit the current prompt with $EDITOR?

[gspeicher]

I echo the sentiments of @nornagon-openai , particularly if basic operations like 3cw aren't even implemented. Is there no rust line editor library like readline/libedit that already contains a more fully featured vi mode implementation? Ideally it would automatically check ~/.inputrc file for the line:

set editing-mode vi

and set vi mode automatically.

Alternatively I think there is a strong argument for a feature where you type something like /edit for the TLI to launch the user's default editor (from $EDITOR) on a temp file which would then be used as the next prompt when a non-empty file is written, similar to git/svn commit log behavior or the PostgreSQL psql \e command.

[coachv270]

I hope Vim mode makes its way into the TUI. As a long-time Vim user who has enjoyed Vim mode in other agentic coding tools, I find its absence here very inconvenient. The efficiency and flow that Vim keybindings provide are hard to match.

I understand the purity arguments against it, but the real-world experience may tell a better story. Just imagine working in the TUI with the bindings, and then having them stripped away. That would create more pain than otherwise.

As for bindings, even a simple set works well. Commands such as . or @ are not necessary. If you find yourself needing those, it is probably a sign you would be better off editing the document in an external editor.

[honjo-hiroaki-gtt]

I propose shipping both:

• /edit to open the current prompt in $EDITOR (opt-in external editing, no auto-send by default).
• /vim as an opt-in minimal Vim keymap inside the TUI—documented as a subset (no Visual/ex/macros), but including the essentials people asked for: counts, ciw/diw, . repeat, d/c/y with motions, p/P, u/, and basic motions (w/e/b, ^/$, gg/G, optional f/t).

This keeps the default experience unchanged while giving power users a safe subset. If that direction sounds good, I’ll split it into two PRs (external editor first), add a cheatsheet and clear “what’s not implemented” notes, and wire a kill-switch so we can turn it off if needed.

[coachv270]

I propose shipping both:

• /edit to open the current prompt in $EDITOR (opt-in external editing, no auto-send by default).
• /vim as an opt-in minimal Vim keymap inside the TUI—documented as a subset (no Visual/ex/macros), but including the essentials people asked for: counts, ciw/diw, . repeat, d/c/y with motions, p/P, u/, and basic motions (w/e/b, ^/$, gg/G, optional f/t).

This keeps the default experience unchanged while giving power users a safe subset. If that direction sounds good, I’ll split it into two PRs (external editor first), add a cheatsheet and clear “what’s not implemented” notes, and wire a kill-switch so we can turn it off if needed.

Appreciate the comment!
I'd vote for including f/t/F/T, as these are among the most useful commands.

[honjo-hiroaki-gtt]

Updated /vim to the minimal subset we outlined—the table documents exactly what’s included, and the docs now call out that it’s a subset.
/edit will follow in a separate PR.

[honjo-hiroaki-gtt]

As a long time Vim user who feels most comfortable editing text in Vim, I'm hesitant to add a Vim emulation mode to the prompt textbox. The reason is that I generally find Vim emulations that are not actually Vim frustrate me more than they delight me, as inevitably they do not support some feature which I rely on to feel comfortable in Vim, e.g. ciw or ..

Would it perhaps make sense to instead add a keyboard shortcut to edit the current prompt with $EDITOR?

@nornagon-openai
Sure! I took your suggestion and opened a follow-up PR that adds a /edit command and Ctrl+E shortcut to round-trip the composer through $EDITOR: #4147 (includes docs + tests).
Let me know what you think!

[msteinert]

I've been testing this patch for about a week (used codex to rebase it against main!) and it works great. It would be nice to have this and a /edit command. A couple other things that would be nice to have:

• I insert at the beginning of the line
• A append at the end of the line
• Some way to remember the /vim setting in the config
• v to open the editor in normal mode, this will be familiar to people used to readline

Great work, thanks!

[honjo-hiroaki-gtt]

I've been testing this patch for about a week (used codex to rebase it against main!) and it works great. It would be nice to have this and a /edit command. A couple other things that would be nice to have:

• I insert at the beginning of the line
• A append at the end of the line
• Some way to remember the /vim setting in the config
• v to open the editor in normal mode, this will be familiar to people used to readline

Great work, thanks!

Thanks a ton for taking this for a spin (and even rebasing it)—really appreciate the feedback!

• I / A: already implemented; they jump to the start/end of the line and enter Insert mode.
• /vim persistence: right now the supported way is to set tui.editor_keymap = "vim" in ~/.codex/config.toml. Remembering the toggle automatically would be a nice follow-up, but it’s a bit out of scope for this minimal subset, so I’d prefer to track it separately.
• Normal-mode v to open the external editor: also unimplemented at the moment. Because plain Vim uses v for Visual mode, wiring it to /edit would be a larger, non-standard change, so I’d rather keep that discussion for afterwards.

I’ve noted both ideas so we can revisit them after the MVP lands. Thanks again!

[msteinert]

* `I` / `A`: already implemented; they jump to the start/end of the line and enter Insert mode.

So they are, not sure how I missed this. Great!

* Normal-mode `v` to open the external editor: also unimplemented at the moment. Because plain Vim uses `v` for Visual mode, wiring it to `/edit` would be a larger, non-standard change, so I’d rather keep that discussion for afterwards.

Visual mode would be even better!

[etraut-openai]

Thanks for the contribution, and apologies for the slow response. We've received many PRs, and we don't have the bandwidth on the codex team to review all of them.

We've updated our contribution guidelines to clarify that we're currently accepting contributions for bugs and security fixes, but we're not generally accepting new features at this time. We need to make sure that all new features compose well with both existing and upcoming features and fit into our roadmap. If you would like to propose a new feature, please file or upvote an enhancement request in the issue tracker. We will generally prioritize new features based on community feedback.

[drice]

Please vote for this idea here