gptme

Maintains stateful conversations across multiple LLM providers (OpenAI, Anthropic, Ollama, etc.) with automatic provider selection and fallback logic. Implements conversation persistence to disk, allowing users to resume multi-turn interactions without losing context. Uses a provider abstraction layer that normalizes API differences across incompatible interfaces, enabling seamless switching between models mid-conversation.

Executes code (Python, shell, etc.) in an isolated environment and feeds execution errors back to the LLM for automatic correction. Implements a feedback loop where the model analyzes error messages, modifies code, and re-executes until success or max retries. Captures stdout, stderr, and exit codes to provide rich error context for the correction prompt.

Manages API keys and provider configuration for multiple LLM services (OpenAI, Anthropic, Ollama, etc.). Implements secure credential storage (environment variables, config files) and provider selection logic. Supports fallback providers if the primary provider is unavailable or exhausted quota.

Saves and loads conversations to disk in a structured format (JSON, YAML, etc.), enabling conversation replay and sharing. Implements serialization of message history, metadata (timestamps, model used, tokens), and conversation state. Supports conversation listing and search by metadata.

Allows the LLM to read, write, create, and modify files on the user's filesystem through natural language commands. Implements a file operation abstraction that interprets high-level intents ('create a config file', 'append logs') into concrete filesystem operations. Maintains a working directory context and supports glob patterns for batch operations.

Fetches web pages, extracts content, and summarizes them using the LLM. Implements HTTP client integration with automatic content parsing (HTML to text), handling of redirects and authentication. The LLM can request specific URLs, and responses are automatically summarized or analyzed based on the original query intent.

Processes images (PNG, JPEG, etc.) and sends them to vision-capable LLMs (GPT-4V, Claude Vision) for analysis. Supports OCR, object detection, scene understanding, and image-to-text conversion. Implements image encoding and multimodal prompt construction, allowing users to ask questions about image content in natural language.

Implements a function registry where tools (code execution, file operations, web browsing, etc.) are exposed to the LLM as callable functions with JSON schemas. The LLM decides when to invoke tools based on user intent, and results are fed back into the conversation. Supports both native provider function-calling APIs (OpenAI, Anthropic) and fallback prompt-based tool invocation for models without native support.

Renders LLM responses to the terminal in real-time as tokens arrive, providing immediate visual feedback. Implements streaming protocol handling for different providers (OpenAI, Anthropic) and formats output with syntax highlighting for code blocks. Supports interactive interruption of long-running responses and graceful handling of stream errors.

Tracks conversation history and manages context windows by counting tokens and pruning old messages when approaching model limits. Implements provider-specific token counting (OpenAI tiktoken, Anthropic token counting API) to accurately estimate context usage. Supports configurable context window sizes and pruning strategies (oldest-first, least-relevant-first).

Maintains conversation state across multiple turns with proper role management (user, assistant, system). Implements message history serialization and deserialization, supporting different message formats across providers. Handles system prompts, user instructions, and assistant responses with proper sequencing and validation.

Parses command-line arguments to construct user prompts and configure agent behavior. Supports both interactive mode (REPL-style) and single-command mode (one-shot execution). Implements argument validation and help text generation, allowing users to invoke the agent with natural language commands directly from the shell.