Shell GPT

Generates platform-specific shell commands by detecting the user's OS and $SHELL environment variable, then presents an interactive prompt ([E]xecute, [D]escribe, [A]bort) before execution. Uses the SHELL role system to inject OS context into the LLM prompt, ensuring generated commands work on Linux, macOS, or Windows. The DefaultHandler routes --shell flag to this role, and sgpt/integration.py handles shell hotkey binding for zero-context-switch invocation.

Maintains stateful chat sessions using the ChatHandler and ChatSession classes, storing conversation history in a local cache (sgpt/cache.py). Each --chat <id> invocation appends the new prompt to the session file and retrieves prior context, enabling multi-turn conversations without re-specifying context. Sessions are stored as JSON or text files in ~/.config/shell_gpt/, making them portable and inspectable.

Manages configuration via ~/.config/shell_gpt/.sgptrc file and environment variables (OPENAI_API_KEY, API_BASE_URL, USE_LITELLM, etc.). The sgpt/config.py module reads configuration at startup, with environment variables taking precedence over file-based settings. On first run, sgpt prompts the user for an OpenAI API key and writes it to .sgptrc. Configuration includes LLM backend selection, cache TTL, default model, and other runtime parameters.

Supports multi-line prompt input via the --editor flag, which opens the user's $EDITOR (e.g., vim, nano, VS Code) to compose the prompt. The sgpt/utils.py module handles editor invocation and captures the edited text as the prompt. This is useful for complex prompts that are difficult to type on a single command line, or for pasting large code blocks that need explanation.

Implements a role system (sgpt/role.py) that wraps user prompts with predefined or custom system instructions. Built-in roles include SHELL (for command generation), CODE (for code snippets), DESCRIBE_SHELL (for explaining commands), and DEFAULT (for general Q&A). Users can create custom roles via --create-role, which stores role definitions as files in ~/.config/shell_gpt/roles/. The DefaultHandler.check_get() method maps CLI flags (--shell, --code, --describe-shell) to roles, then injects the role's system prompt before sending to the LLM.

Caches LLM responses using sgpt/cache.py, which stores responses keyed by prompt hash and role. Enabled by default via --cache flag; can be disabled with --no-cache. Cache entries include a TTL (time-to-live) that is configurable in ~/.config/shell_gpt/.sgptrc. When a cached response is found, sgpt returns it immediately without calling the LLM, reducing latency and API costs. Cache is stored as JSON files in ~/.cache/shell_gpt/ or equivalent platform cache directory.

Provides a read-eval-print loop (REPL) via the --repl <id> flag, implemented by ReplHandler class. Each iteration accepts a new prompt, sends it to the LLM with prior conversation context, and displays the response without exiting. The REPL maintains session state in memory and persists it to disk (via ChatSession), allowing users to iterate rapidly without re-invoking sgpt. Supports multi-line input via editor integration (--editor flag) for complex prompts.

Abstracts LLM backend selection via sgpt/handlers/handler.py and a configuration flag USE_LITELLM in ~/.config/shell_gpt/.sgptrc. Supports OpenAI API (default), Ollama/local models (via LiteLLM), and Azure OpenAI by routing API calls through either the native OpenAI client or the LiteLLM library. Backend selection is determined at runtime based on configuration, allowing users to swap providers without code changes. The Handler base class owns all LLM interaction, making backend-specific logic centralized.

Implements LLM function calling via sgpt/function.py and sgpt/llm_functions/ directory, allowing the LLM to request execution of predefined functions (e.g., file operations, system commands). The Handler base class processes function-call responses from the LLM, executes the requested function, and feeds the result back to the LLM for further reasoning. Functions are registered in a schema-based registry that is passed to the LLM as part of the system prompt, enabling the LLM to decide when and how to invoke them.

Provides shell integration via --install-integration flag, which installs a shell hotkey (e.g., Ctrl+G) that invokes sgpt without leaving the terminal. The integration is implemented in sgpt/integration.py and sgpt/utils.py, and works by injecting shell functions or aliases into ~/.bashrc, ~/.zshrc, or equivalent. When the hotkey is pressed, the current line is passed to sgpt as a prompt, and the result is inserted back into the shell prompt for editing or execution.

Generates code snippets via the --code flag, which activates the CODE role and disables markdown formatting. The DefaultHandler routes --code to the CODE role, which injects a system prompt instructing the LLM to output raw code without markdown backticks or language tags. Output is printed directly to stdout without formatting, making it suitable for piping to files or other commands (e.g., sgpt --code 'write a python function' > script.py).

Explains shell commands via the --describe-shell flag, which activates the DESCRIBE_SHELL role. The DefaultHandler routes --describe-shell to this role, which injects a system prompt instructing the LLM to break down a command into its components (flags, arguments, pipes, etc.) and explain what each part does. Output is formatted as structured text (e.g., bullet points or paragraphs) rather than raw code, making it suitable for learning or documentation.