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 fzf-powered key bindings for your shell, such as CTRL-T for files and CTRL-G CTRL-H for commit hashes, are no longer there to help you. They 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.

What happens in the screencast (the responses of Claude Code are sped up):

• 0:05: Type “Summarize changes since " into the prompt of Claude Code.
• 0:09: PREFIX`` g``h to list commit hashes. PressCTRL-/ to change the layout of the preview window, and look for the commit to start from.
• 0:16: Select the commit. Its hash is inserted into the prompt.
• 0:25: PREFIX`` CTRL-T to start tmux-fzf-complete.CTRL-T to go through files, directories, and paths, to the sentences on the screen.
• 0:28: Type “mouse” to find a sentence in the response, and select it.
• 0:31: Type “Elaborate” below the sentence, and send it.
• 0:35: While Claude Code is working, PREFIX`` CTRL-T again, andCTRL-T to go to the paths on the screen.
• 0:40: CTRL-O to opensrc/tui/light.go in Vim, in the floating pane.
• 0:42: PREFIX`` z to zoom the pane, and search for “mouse” in the file.
• 0:46: PREFIX`` z to unzoom. Quit Vim to go back to fzf, and close it.

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,

set -g @plugin 'junegunn/tmux-fzf-complete'

or clone the repository and run fzf-complete.tmux from your .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 pressPREFIX`` 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 , orcodex --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.

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 forF iles
• PREFIX`` g``b forB ranches
• PREFIX`` g``t forT ags
• PREFIX`` g``r forR emotes
• PREFIX`` g``h for commitH ashes
• PREFIX`` g``s forS tashes
• PREFIX`` g``l for refl ogs
• PREFIX`` g``w forW orktrees
• PREFIX`` g``e forE ach ref (git for-each-ref )
• PREFIX`` g``p for GitHubP ull requests (only ifpr.fzf is in$PATH )

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. Likewise, PREFIX g p fills in the numbers of the pull requests you want the agent to review.