Using fzf with AI coding agents #

The problem #

With AI coding agents such as Claude Code and Codex, you spend more of your time typing into the prompt of the agent than on the command line of your shell. You still need to type in file paths, commit hashes, and branch names, but the key bindings of the shell integration are no longer there to help you. CTRL-T and CTRL-R are handled by the shell, and the shell is not the program reading your keys anymore.

tmux to the rescue #

If you run the agents inside tmux, as many people do, tmux key bindings still work. tmux sees the keys before the program in the pane does, so a key bound in tmux works whatever the pane is running. It can start fzf in a floating pane, and send the selection back to the original pane as key strokes, as if you typed it.

There are two plugins built this way.

The floating pane requires tmux 3.7 or later. On older versions, fzf starts in a popup instead.

tmux-fzf-complete #

tmux-fzf-complete makes CTRL-T of fzf available in every tmux pane. It requires fzf 0.74.0 or later, and Ruby. Install it with TPM,

# ~/.tmux.conf
set -g @plugin 'junegunn/tmux-fzf-complete'

or clone the repository and run fzf-complete.tmux from your .tmux.conf.

# ~/.tmux.conf
run-shell /path/to/tmux-fzf-complete/fzf-complete.tmux

Press PREFIX CTRL-T in the prompt of an agent. The word in front of the cursor becomes the query, and the selection replaces it.

~/github/fzf-g      ->      ~/github/fzf-git.sh/README.md

It completes more than files. Inside fzf, CTRL-T goes to the next provider, and these keys switch to one directly.

The last three are especially useful with an agent. An agent prints a lot of paths and URLs, and you often want to refer to one of them in your next message. A sentence is put back together from the rows the agent wrapped it into, with its indentation removed, so you can quote a part of the answer of the agent without copying it with the mouse.

Some other keys inside fzf:

• CTRL-O opens the item under the cursor, a URL in the browser and anything else in $EDITOR, and comes back to fzf after. The editor opens in the floating pane, so press PREFIX z to zoom the pane if you need more room.
• CTRL-Y copies the selection to the clipboard.
• CTRL-R reloads the list, so you can pick up the latest output of the agent.

Keep the output of the agent in the scrollback #

An agent that draws a full screen keeps no scrollback in tmux, so only what is currently on the screen can be completed from. Claude Code and Codex can draw on the main screen instead, which leaves their output in the scrollback.

• Claude Code: /tui default in a session, or "tui": "default" in ~/.claude/settings.json
• Codex: alternate_screen = "never" under [tui] in ~/.codex/config.toml, or codex --no-alt-screen

fzf-git.sh #

fzf-git.sh provides key bindings for Git objects. In addition to the shell bindings, it now comes with tmux bindings in fzf-git.tmux. Keep it in the same directory as fzf-git.sh.

# ~/.tmux.conf
run-shell /path/to/fzf-git.tmux

The keys are the same as the shell bindings, with PREFIX g in place of CTRL-G.

• PREFIX g ? to show the list
• PREFIX g f for Files
• PREFIX g b for Branches
• PREFIX g t for Tags
• PREFIX g r for Remotes
• PREFIX g h for commit Hashes
• PREFIX g s for Stashes
• PREFIX g l for reflogs
• PREFIX g w for Worktrees
• PREFIX g e for Each ref (git for-each-ref)

So you can ask the agent to “review the changes in” a commit, and fill in the hash with PREFIX g h after looking at the diff of each commit in the preview window.