ShellGPT turns terminal input into prose, code, or commands
ShellGPT is easy to understand at its safest setting. Run sgpt with a question, pipe a log or diff into it, or ask for code-only output. Shell mode asks the model for one command tailored to the detected operating system and shell, then presents Execute, Modify, Describe, and Abort choices. Chat and REPL modes retain conversation state, while named roles let users set a reusable response instruction.
The shell integration goes a step further by adding a hotkey to Bash or Zsh startup files. Pressing the configured key sends the current command line as a prompt and replaces the terminal buffer with the suggestion. The user can edit it before pressing Enter. That is the right interaction model for generated commands: the model drafts, the shell displays, and the operator owns execution. PowerShell is supported as a shell for suggestions, though the documented hotkey installer targets Bash and Zsh.
The 61 MB install is small, while provider setup is unavoidable
Our sandbox installed 53 Python packages in 38 seconds and used 61 MB. The project build completed in 9 seconds. Pip-audit found 0 known vulnerabilities in the installed dependencies. The checkout itself was 0.1 MB with 42 files and roughly 2,758 source lines, making this one of the easiest repositories in the batch to inspect and package.
Default setup prompts for an OpenAI API key and stores it in ~/.config/shell_gpt/.sgptrc; an environment variable can supply it instead. API use is billed by the provider. The README also documents an Ollama route, but warns that ShellGPT is not optimized for local models. Other compatible endpoints can be selected through the base URL, model, and LiteLLM settings, yet issue 578 records an LM Studio compatibility failure that remained open.
What happened when we ran it
Our test command exited with code 1 after 8 seconds. Pytest reported 0 passed, 0 failed, and 4 collection or setup errors out of 4. The errors covered tests/test_code.py, test_default.py, test_roles.py, and test_shell.py. Each said pytest could not read stdin while output was captured and suggested using -s.
The log also contained 4 GetPassWarning messages from Python's getpass, saying it could not control terminal echo. That is the complete diagnosis available in the supplied tail. We did not inject a key or change capture settings, so no functional assertion ran and no live model request was made. The 9-second build proves the package can be assembled at commit a082bd5; it does not verify code generation, shell safety, caching, or provider compatibility.
Function calling bypasses the safer shell confirmation path
Shell mode shows a generated command and asks before execution. The optional function system is different. Users can install Python functions whose names and docstrings are sent to the model, and one bundled example exposes arbitrary shell execution. The README itself warns that a model may run destructive commands and tells users to proceed at their own risk.
Open issue 793 makes the concern specific. It reports that function calling is enabled by default through OPENAI_USE_FUNCTIONS=true, and that the execute_shell_command function runs a model-proposed string with shell=True without the Execute or Abort prompt used by shell mode. The report says function output is hidden by default as well. Until that behavior changes, set function use to false, remove the executing function, or run ShellGPT inside a disposable environment with narrow permissions.
Piped logs leave the machine and replies stay in local caches
A convenient example sends docker logs to the model for diagnosis. Another pipes git diff to produce a commit message. Both can contain secrets, customer data, internal hostnames, or unreleased source. ShellGPT sends the prompt to the configured model endpoint. Teams should choose an approved provider route, redact inputs, and avoid shell-history expansion that inserts more data than intended.
Responses and chat sessions can also persist locally. The config includes separate request and chat cache paths, with a default chat length of 100 messages and request caching enabled. That state is useful for continuity and cost control, but it belongs outside shared temporary directories when prompts are sensitive. File permissions, retention, backup, and deletion should be part of setup rather than left to defaults.
Current model documentation conflicts inside the same README
The installation section still says ShellGPT uses GPT-4 by default. Farther down, the runtime configuration example sets DEFAULT_MODEL=gpt-5.4-mini, and release 1.5.1 says it changed the default to that model. The release was published May 6, 2026. Users should trust the installed version's generated config and release notes over the older introductory sentence, then pin a model explicitly if reproducibility matters.
GitHub showed 12,259 stars, 118 combined open issues and pull requests, and a last repository push on July 2, 2026. Issue 793 was opened on August 5, showing ongoing user scrutiny after that push. ShellGPT remains a handy terminal front end, but its most consequential capability is also its sharpest edge. Keep it in suggestion mode, inspect every command, and treat functions as executable code rather than chat features.