What is djcopley/ShellOracle?

ShellOracle turns a plain-language description into a command inserted directly into your BASH, ZSH or fish buffer. It is a thin Python client over a provider you choose, and that choice decides almost everything about how well it works.

Can I use djcopley/ShellOracle commercially?

Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.

Is djcopley/ShellOracle still maintained?

Yes. The repository last received commits 3 days ago.

What programming language is djcopley/ShellOracle written in?

Mainly Python, according to GitHub's language statistics.

ShellOracle: shell command generation via Ctrl+F

At a glance

What is it?: ShellOracle turns a plain-language description into a command inserted directly into your BASH, ZSH or fish buffer. It is a thin Python client over a provider you choose, and that choice decides almost everything about how well it works.
Who is it for?: Adopt ShellOracle if you already run a shell you can bind keys in and you either want a local model through Ollama or llmman, or you are comfortable sending your descriptions to OpenAI, Google, Deepseek or XAI with an API key in ~/.shelloracle/config.toml. Skip it if you cannot install Python 3.10 or newer, if you need Windows, or if you are not willing to read the generated command before pressing Enter.
Can I use it commercially?: Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?: Yes. The repository last received commits 3 days ago.
What is it written in?: Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.

DEEP OPEN-SOURCE ANALYSIS

Hysen Labs Editorial · September 15, 2026 · djcopley/ShellOracle

The gap ShellOracle fills between knowing what you want and typing it

Most command-line friction is not conceptual. You know you want to find every Python file under the current directory, you just do not remember whether it is find with -name or fd with a pattern, and whether the extension needs a glob. ShellOracle targets exactly that gap. You describe the command in words, and the tool puts a candidate command into your shell buffer, where you can still edit it before running anything. The README frames it as a widget activated by CTRL+F in BASH, ZSH and fish, and that framing matters: the output lands in your prompt, not in a separate chat window you then copy from. The audience is developers on macOS and Linux who spend enough time in a terminal that a two-second detour to a browser is annoying. The pyproject.toml classifier list confirms the scope: macOS and POSIX Linux only, Python 3.10 through 3.14, console environment. There is no Windows claim anywhere in the repository.

How a description becomes a command in your buffer

ShellOracle is a client, not a model. The pyproject.toml dependency list shows what it actually is: click for the CLI, prompt-toolkit for the interactive prompt, httpx and the openai package for HTTP, rich and pygments for terminal rendering, yaspin for the spinner, tomlkit for config editing. The intelligence comes from a provider you select during configuration. The README lists Ollama, llmman, OpenAI, Deepseek, LocalAI and Grok as supported, and the configuration example for LM Studio shows the general shape: a provider name plus a base_url, api_key and model. So the data flow is roughly: you press CTRL+F, prompt-toolkit collects your description, the description goes over HTTP to whichever endpoint the config points at, and the returned text is inserted into the ZLE or fish buffer. Two details in the README are worth noting. Text left of your cursor in the ZLE buffer carries over into the ShellOracle prompt, which means you can select part of an existing command and describe only the rest. And ShellOracle can be piped, so the prompt can come from stdin rather than the widget.

Installing ShellOracle with pipx and running the first command

The README prefers pipx over pip for environment isolation, and the install is two steps: install the package, then run the configuration wizard. The wizard is where you pick a provider, and it is the step that decides whether the tool works at all.

bash

pipx install shelloracle
shor config init

After the wizard finishes, `shor` is the entrypoint, defined in pyproject.toml as `shor = "shelloracle.cli:main"`. If you chose a local provider, the model has to exist before ShellOracle can use it. For Ollama the README gives this example, assuming you picked `gemma4:12b` in the wizard:

bash

ollama pull gemma4:12b

For llmman, which the README says serves the Ollama API on port 17434, the sequence is to start the server and pull the model:

bash

llmman serve
llmman pull gemma4

Once a provider is reachable, the interactive path is the point of the tool: press CTRL+F, type a description, press Enter, and the generated command appears in your prompt. The README notes that running ShellOracle as `python3 -m shelloracle` or as `shor` works too, but that this way does not insert the result into your prompt automatically. That is the fallback path, and it is also the one to use when you want to see the raw output before it touches your buffer.

Pointing ShellOracle at LM Studio or any OpenAI-compatible endpoint

The most useful configuration detail in the README is the LM Studio example, because it shows the escape hatch: a generic `OpenAICompat` provider that talks to any server exposing an OpenAI-shaped API. If your local runtime is not on the named list, this is the provider to try.

toml

[shelloracle]
provider = "OpenAICompat"

[provider.OpenAICompat]
base_url = "http://localhost:1234/v1"
api_key = "lm-studio"
model = "mistralai/devstral-small-2507"

The file lives at `~/.shelloracle/config.toml`, and `shor config edit` opens it. The README recommends the MLX runtime for macOS users running LM Studio. The api_key value here is a placeholder the local server accepts, not a secret, which is a small but real convenience: local providers do not require you to manage credentials. The trade-off is that you own the endpoint's availability. If the server is not running, ShellOracle has nothing to talk to.

What ShellOracle does not do, and where it is the wrong tool

ShellOracle generates a command. It does not explain one, it does not verify that the command is safe, and the README does not describe any confirmation step, dry-run mode or sandbox before the text reaches your buffer. A model that misreads a description like "delete the old log files" can produce something destructive, and the tool's own design assumes you will read the line before pressing Enter. Treat that as the operating contract, not a footnote. Second, the README documents no Windows support and the pyproject.toml classifiers list only macOS and POSIX Linux, so Windows users are out of scope. Third, the project is a client, so quality tracks the provider: a small local model will produce worse commands than a hosted frontier model, and the README does not offer guidance on which model to pick beyond the provider setup. Fourth, the README does not document rollback, undo, or any way to retrieve a previously generated command other than the prompt history cycled with the arrow keys. If you need an audit trail of what was suggested and what you ran, you will have to build it outside the tool.

ShellOracle versus a general chat assistant or a shell alias

The obvious alternative is asking a chat model in a browser or a separate terminal pane and pasting the result. The difference is the buffer. A chat assistant returns text you then copy, edit and run, and the context of your current command line is lost unless you describe it. ShellOracle inserts into the buffer and, per the README, carries over the text left of your cursor, so a partial command can be completed in place. That is a genuinely different interaction, not a cosmetic one. The other alternative is the low-tech one: shell aliases and functions for the commands you type often. Those are deterministic, instant, and have no provider to configure. ShellOracle is for the long tail of commands you type rarely enough that an alias never gets written, which is also the case where a wrong answer is most likely because you cannot spot it from memory. If your work is dominated by twenty commands you already know, aliases will beat ShellOracle on every axis.

Maintenance, upgrades and the GPL-3.0 licence

The last push to the default branch was on 2026-09-13, and the most recent release, v1.12.0, carries the same timestamp. The release before that, v1.11.0, is also dated 2026-09-13, while v1.10.0 is from 2026-03-08, so the cadence is uneven: long quiet stretches punctuated by bursts. Upgrading is a single command, `pipx upgrade shelloracle`, which is the main reason the README prefers pipx over pip. The configuration file is TOML and is edited in place, so an upgrade that changes config keys would surface as a parse or validation problem rather than a silent migration; the README does not describe a migration path. On licensing, ShellOracle is GPL-3.0, confirmed both in the README and in the pyproject.toml classifier. If you are considering embedding it in a closed-source product or shipping it as part of a proprietary tool, the copyleft terms are the thing to read before you start, and that is a question for your own legal review rather than something this article can settle. Running it as an end user in your own terminal is the ordinary case the licence is built for.

Editorial conclusion

Adopt ShellOracle if you already run a shell you can bind keys in and you either want a local model through Ollama or llmman, or you are comfortable sending your descriptions to OpenAI, Google, Deepseek or XAI with an API key in ~/.shelloracle/config.toml. Skip it if you cannot install Python 3.10 or newer, if you need Windows, or if you are not willing to read the generated command before pressing Enter. Verify first that your chosen provider is reachable, that the model name in the config matches a model you actually pulled or selected, and that the CTRL+F binding does not collide with an existing widget in your shell.

Frequently asked questions

How do I install ShellOracle?

The README gives two steps: `pipx install shelloracle`, then `shor config init` and follow the prompts. The README states that pip install is supported but pipx is preferred for automatic environment isolation.

Which providers does ShellOracle support?

The README lists Ollama, llmman, OpenAI, Deepseek, LocalAI and Grok. It also documents an OpenAICompat provider for servers exposing an OpenAI-shaped API, with LM Studio as the worked example.

Where is the ShellOracle configuration file?

It is at ~/.shelloracle/config.toml, and the README gives `shor config edit` as a shorthand for opening it. Provider, base_url, api_key and model are set there.

Official sources

Community notes