Shell GPT

Generates platform-specific shell commands by detecting the user's OS and active shell ($SHELL environment variable), then presents an interactive prompt allowing execution, description, or abortion of the generated command. The DefaultHandler routes the --shell flag to a SHELL SystemRole that constrains LLM output to executable commands. After generation, sgpt parses the response and offers [E]xecute, [D]escribe, [A]bort options, with --no-interaction flag enabling pipeline-friendly non-interactive mode that writes directly to stdout.

Implements a SystemRole abstraction (defined in sgpt/role.py) that wraps user prompts with role-specific system instructions before sending to the LLM. Built-in roles include SHELL (command generation), DESCRIBE_SHELL (command explanation), CODE (code generation), and GENERAL (Q&A). Roles are selected via CLI flags (--shell, --describe-shell, --code) and mapped through DefaultRoles.check_get() in app.py. Custom roles can be created and persisted via --create-role, allowing users to define domain-specific prompt templates that are reused across sessions.

Allows users to compose prompts in their preferred text editor via the --editor flag, which opens $EDITOR (or a configured editor) for prompt composition. This is useful for long, complex prompts that are cumbersome to type on the command line. The editor integration is implemented in sgpt/utils.py and captures the editor's output as the prompt text. After the user saves and closes the editor, the prompt is sent to the LLM. This enables multi-line prompts, code snippets, and formatted text without shell escaping.

Manages tool configuration via ~/.config/shell_gpt/.sgptrc, a file-based configuration store that persists settings across invocations. Configuration includes API keys, backend selection (USE_LITELLM), model choice, cache TTL, and custom roles. The config.py module handles reading and writing configuration, with sensible defaults for unset values. On first run, sgpt prompts the user for an OpenAI API key and writes it to .sgptrc. Configuration can also be overridden via environment variables (e.g., OPENAI_API_KEY, API_BASE_URL), allowing both file-based and environment-based configuration.

Abstracts LLM provider selection through a Handler base class (sgpt/handlers/handler.py) that supports OpenAI (default), Azure OpenAI, and OpenAI-compatible servers (Ollama, local models) via LiteLLM. Backend selection is controlled by the USE_LITELLM config flag in ~/.config/shell_gpt/.sgptrc and environment variables (API_BASE_URL, OPENAI_API_KEY). The Handler class owns client initialization, request routing, and response streaming, allowing providers to be swapped without changing CLI or role logic. LiteLLM is an optional dependency; if not installed, the tool falls back to OpenAI's official client.

Maintains multi-turn conversations using the --chat <id> flag, which routes requests to ChatHandler instead of DefaultHandler. Chat sessions are persisted to disk (location managed by sgpt/cache.py) with full conversation history, allowing users to reference previous messages and build context across multiple invocations. Each session is identified by a unique ID; the same ID can be reused to continue a conversation. Session state includes all prior user prompts and LLM responses, enabling the LLM to maintain context without re-sending the entire history on each request (handled by the Handler's context management).

Provides a read-eval-print loop (REPL) via the --repl <id> flag, which routes requests to ReplHandler and creates an interactive shell-like environment where users can issue multiple prompts in sequence without restarting the tool. Each REPL session maintains state (conversation history, role context) across multiple user inputs, similar to chat sessions but with a continuous interactive loop. The REPL mode is useful for exploratory tasks where users want rapid iteration without the overhead of invoking sgpt multiple times.

Caches LLM responses to disk using sgpt/cache.py, reducing API calls and latency for repeated or similar prompts. Caching is enabled by default (--cache flag) and uses a hash of the prompt, role, and other parameters as the cache key. Cached responses are stored in ~/.config/shell_gpt/ with configurable time-to-live (TTL); expired cache entries are automatically invalidated. The cache is transparent to users — if a cached response exists, it is returned without making an API call. Cache behavior can be controlled via configuration flags.

Enables the LLM to call external functions via a schema-based function registry (sgpt/function.py and sgpt/llm_functions/). Functions are defined with JSON schemas that describe their parameters and return types, and the LLM can invoke them as part of its response generation. The function calling system integrates with the Handler base class, which detects function calls in LLM responses, executes the corresponding functions, and feeds results back to the LLM for further processing. Built-in functions are provided in sgpt/llm_functions/ (e.g., shell command execution, file operations), and custom functions can be registered.

Provides shell hotkey integration via the --install-integration flag, which installs shell-specific keybindings (e.g., Ctrl+L in Bash/Zsh) that invoke sgpt with the current command line as the prompt. The integration is implemented in sgpt/integration.py and sgpt/utils.py and modifies shell configuration files (~/.bashrc, ~/.zshrc, etc.) to add the hotkey binding. When the hotkey is pressed, the current command line is captured, sent to sgpt, and the response is inserted back into the shell prompt for review or execution. This enables users to invoke sgpt without leaving the shell or typing the sgpt command.

Generates code snippets via the --code flag, which routes requests to the CODE SystemRole and disables markdown formatting in the response. The CODE role constrains the LLM to generate clean, executable code without explanatory text or markdown code blocks. Output is formatted as raw code suitable for piping to files or other tools (e.g., sgpt --code 'generate a Python function' > script.py). The Handler base class manages response streaming and formatting, ensuring that code output is not wrapped in markdown or other decorations.

Explains shell commands via the --describe-shell flag, which routes requests to the DESCRIBE_SHELL SystemRole. This role constrains the LLM to provide clear, human-readable explanations of shell commands, breaking down syntax, flags, and behavior. Users can pass an existing command (e.g., sgpt --describe-shell 'find . -type f -name "*.json"') and receive a detailed explanation. This is useful for understanding unfamiliar commands or documenting complex shell scripts.