claude-code.fish

Claude-powered helpers for your fish prompt. Ask questions, explain commands, and turn natural language into shell commands - without leaving the terminal.

All four features wrap the claude CLI (Claude Code) in --print mode, so if you're already logged in with claude auth login there's nothing else to set up.

• Ctrl+X - describe a command in plain English, press to rewrite the line into shell.
• Alt+E - type or paste a command, press to print an explanation above it.

Features

	What	Trigger	Default model
Ask	Terse answer to any dev/terminal question	ask <question>	sonnet
Explain	Summarize a command in natural, concise English	explain <command>	sonnet
Suggest widget	Rewrite the current line (natural language) → one shell command, in place	Ctrl+X	haiku
Explain widget	Explain the command at the prompt, above it (command stays intact)	Alt+E	sonnet

Each call is one-shot: no saved session, no tools, no slash commands. Your user-level Claude settings and CLAUDE.md still apply, so a preference like "use fd instead of find" shapes the suggestions. Project-level settings and MCP servers are ignored.

Requirements

• fish 3.4+
• claude CLI installed and authenticated (either claude auth login or ANTHROPIC_API_KEY in the environment)
• Fisher to install
• No other runtime dependencies

Installation

fisher install the-jay-schwartz/claude-code.fish

Open a new shell, or run exec fish.

Usage

ask

ask how do I list files modified in the last 24 hours
ask 'what is the difference between $* and $@ in bash?'

Prints a terse answer. If the answer is a command, it shows the command first in a fenced block, then at most one short line of context.

explain

explain 'find . -type f -exec md5sum {} + | sort | uniq -w32 -dD'

Prints one overview line + a short list item per flag/argument. Tab completes the command.

fish parses the line before ask or explain sees it. Wrap the argument in single quotes whenever it contains *, $, |, ;, > or <. An unquoted * that matches nothing is a fish error, and the command never runs.

Suggest widget (Ctrl+X)

Type a natural-language request, then press Ctrl+X:

find all js files larger than 100kb modified in the last week

becomes:

find . -name "*.js" -size +100k -mtime -7

Review the command, press Enter to run (or edit first). The suggestion is never run for you. If the reply is more than one line, it is not inserted.

Explain widget (Alt+E)

Type or paste a command at the prompt, then press Alt+E. The explanation prints above the prompt; your command stays intact so you can still edit or run it.

The keys are bound in default and insert modes, and only if claude is on PATH at the first prompt.

Configuration

Set any of these in ~/.config/fish/config.fish. The keys are read once, at the first prompt, so changing one needs a new shell.

Variable	Default	Description
CLAUDE_FISH_ASK_MODEL	sonnet	Model for ask
CLAUDE_FISH_EXPLAIN_MODEL	sonnet	Model for explain + explain widget
CLAUDE_FISH_SUGGEST_MODEL	haiku	Model for the suggest widget
CLAUDE_FISH_SUGGEST_KEY	\cx	Keybind for the suggest widget
CLAUDE_FISH_EXPLAIN_KEY	\ee	Keybind for the explain widget (\ee = Alt+E)
CLAUDE_FISH_ASK_SYSTEM_PROMPT	(built-in)	Full override of the ask system prompt
CLAUDE_FISH_EXPLAIN_SYSTEM_PROMPT	(built-in)	Full override of the explain system prompt
CLAUDE_FISH_SUGGEST_SYSTEM_PROMPT	(built-in)	Full override of the suggest system prompt
CLAUDE_FISH_EXTRA_FLAGS	(empty)	Extra flags appended to every claude --print call (advanced)

CLAUDE_FISH_EXTRA_FLAGS must be a fish list, for example set -g CLAUDE_FISH_EXTRA_FLAGS --effort low. A single quoted string such as '--effort low' is passed as one argument. Only --effort, --max-budget-usd and --fallback-model (alone or as flag=value) are allowed. Any other flag is refused, so tools, permissions, settings and MCP cannot be changed.

Example: change keybind and use a faster suggest model

# ~/.config/fish/config.fish
set -g CLAUDE_FISH_SUGGEST_KEY \cg       # Ctrl+G instead of Ctrl+X
set -g CLAUDE_FISH_SUGGEST_MODEL sonnet  # faster, more expensive

Privacy

explain and the explain and suggest widgets send the command line to the Claude API.

Troubleshooting

• "the 'claude' command was not found" - the plugin loads but binds no keys when claude isn't on PATH. Install Claude Code and run claude auth login.
• Widget doesn't fire - another plugin may have rebound the key. Try setting CLAUDE_FISH_SUGGEST_KEY to something else, or use bind | grep __ccf to confirm the binding.
• Output has stray backticks / code fences - the suggest widget strips one surrounding fence or pair of backticks. If more appear, tighten CLAUDE_FISH_SUGGEST_SYSTEM_PROMPT, or open an issue with the input that produced it.

When you are logged out

If claude is logged out, the features say so instead of failing: ask: claude is not logged in; run 'claude auth login'.

• ask and explain offer Log in now? [y/N] when run in a terminal. Press y to run claude auth login, and the command is retried once.
• Ctrl+X and Alt+E always make the same offer and retry once.
• Press anything else, or cancel the login, and your command line stays as it was.

Contributing

Contributions welcome - PRs, bug reports, feature ideas. Tests use fishtape with a stub claude on PATH, so they run offline:

fisher install jorgebucaran/fishtape
fishtape tests/*.test.fish

Commits follow Conventional Commits (feat:, fix:, docs:, chore:, …).

Manual test checklist before sending a PR that touches the plugin code:

• ask and explain with ?, !, *, and quoted strings
• Ctrl+X with a clear request and an ambiguous one
• Alt+E on a typed command - original command must stay intact
• All four features with claude logged out → helpful error, not a crash
• All four features logged out, then y (the retry works), n (the line is kept), and Ctrl+C in the login (the line is kept)
• Alt+E and a failing Ctrl+X with a two- or three-line prompt - the whole reply and the error message must stay visible above the redrawn prompt
• Custom keybinds set before plugin load

See CLAUDE.md for design notes and the reasoning behind each decision.

Contributors

Jay Schwartz 💻 📖 ⚠️ 🚇 🤔

Matheus Poli 🤔

This project follows the all-contributors specification. Contributions of any kind are welcome. After a merged PR, comment on it to add yourself:

@all-contributors please add @your-username for code, doc

Other shells

Shell	Project
zsh	matheus-poli/zsh-claude-code
fish	the-jay-schwartz/claude-code.fish (this project)

License

MIT © Jay Schwartz

Credits

The behavior and feature set come from matheus-poli/zsh-claude-code (MIT © Matheus Poli), and parts of this README are adapted from its README. See THIRD_PARTY_LICENSES for the notice that covers that text.