TUI: support shell command autocomplete in `!` mode

What variant of Codex are you using?

CLI / TUI

What feature would you like to see?

Codex TUI should support shell-style autocomplete when composing local shell commands in ! mode.

Today, ! mode makes the composer behave like a shell command entry point, but pressing Tab does not complete commands or paths the way users expect from a terminal. This breaks a common workflow: using Codex as the main working surface while running quick local commands without switching to a separate terminal tab.

Examples:

!gi<Tab>              -> !git
!ls ~/Doc<Tab>        -> !ls ~/Documents/

For comparison, Claude Code documents narrower ! shell-mode affordances: history-based completion for previous ! commands and file path autocomplete for slash-containing path tokens. Codex has the same ! shell-command concept, but does not currently provide comparable completion behavior in that mode.

Longer term, native shell completion would also allow shell-provided completions such as:

!git checkout ma<Tab> -> !git checkout main
!npm run bu<Tab>      -> !npm run build

Current behavior

! commands can be entered in the TUI, but Tab does not provide shell command completion.

There is also an existing Tab ambiguity: Tab can be used to queue prompts, while terminal users commonly expect it to trigger completion. This is especially surprising in ! mode because the composer is explicitly being used as a shell command entry point.

Expected behavior

When the composer is in ! shell-command mode:

1. Tab should attempt shell command completion.
2. If there is exactly one completion, apply it.
3. If there are multiple completions, show the existing completion popup/list UI.
4. If no completion is available, preserve the current safe behavior and do not accidentally submit or queue a partial shell command.
5. Prompt queueing via Tab should remain available outside completion contexts, but ! mode should treat Tab as completion-first.

Why this matters

This is terminal parity for the command-entry surface Codex already exposes.

The value is not only convenience. It lets users stay inside the agent window while doing common local operations:

• inspect files
• run scripts
• use git
• switch branches
• pass paths to tools
• iterate without context switching to another terminal tab

The current behavior makes ! mode feel like a shell visually, but not operationally.

Related issues

• #14673 asks for shell-like path autocomplete directly in the composer.
• #12939 is not about ! commands specifically, but it is relevant because it tracks the existing Tab ambiguity between completion-like behavior and prompt queueing.

This issue is narrower than general composer path completion: it focuses specifically on shell command completion in ! mode.

Possible implementation shape

A staged approach seems safer than implementing full native shell parity immediately.

Stage 1: basic provider

Add shell completion for ! mode using Codex-owned logic:

• complete executable names from PATH in command position
• complete filesystem paths in argument position
• support ~, ./, ../, and absolute paths
• reuse the existing TUI completion popup where possible
• make Tab completion-first while composing ! commands

This stage would already cover common cases such as:

!gi<Tab>
!ls ./codex-r<Tab>
!cat ~/Doc<Tab>

This stage would not support shell-native dynamic completions such as git branches, npm scripts, cargo targets, or kubectl resources.

Stage 2: native shell backend

Add a native backend that asks the user’s shell for completions. The shell should be detected from the environment, for example $SHELL.

If native completion is unavailable or fails, Codex should fall back to the basic provider automatically.

Possible config:

[tui.shell_completion]
mode = "basic" # off | basic | native

basic can be the default first implementation. native can be added later once the backend is ready.

UX / compatibility considerations

• Tab currently has queueing semantics; in ! mode completion should take priority.
• Completion must not execute shell commands.
• The basic provider should be cross-platform where possible.
• Native shell backends can be added incrementally per shell.
• Behavior should be covered by TUI tests/snapshots where the completion popup changes visible UI.

Potential first PR scope

If maintainers agree with this direction, I would keep the first PR limited to:

• ! mode completion controller
• basic PATH executable completion
• basic filesystem path completion
• Tab handling in ! mode
• focused TUI tests

Native bash/zsh completion would be a follow-up, not part of the first PR.

Happy to contribute a focused PR if the Codex team wants to invite one.

Additional information

_No response_