Mods

Abstracts multiple LLM providers (OpenAI, Anthropic, Google, Cohere, Ollama) behind a unified streaming interface initialized in startCompletionCmd(). Each provider implements a client that handles authentication, model resolution, and real-time token streaming. The system resolves the target model, instantiates the appropriate provider client, and pipes streamed tokens through a message context handler that buffers and formats output for terminal rendering.

Implements a multi-layered configuration cascade (config.go ensureConfig) that merges settings from embedded template defaults, user config file (~/.config/mods/mods.yml via XDG), environment variables (MODS_*, OPENAI_API_KEY), and CLI flags with explicit precedence rules. CLI flags override environment variables, which override config file, which override embedded defaults. The Config struct is populated by binding pflag flags to struct fields, enabling both programmatic and user-facing configuration.

Automatically generates or accepts user-provided titles for conversations (via --title flag) that are stored alongside conversation history in the SQLite database. Titles enable users to identify and retrieve conversations by name rather than ID. The system can generate titles from the first message or accept explicit titles from the user.

Implements an optional caching layer (internal/cache) that stores LLM responses and provider metadata to avoid redundant API calls. The cache is keyed by request hash (prompt, model, parameters) and stores responses with metadata (timestamp, provider, model). Cache hits bypass the LLM provider entirely, returning cached responses instantly. Cache behavior is controlled via configuration and can be disabled for real-time responses.

Mods detects code blocks and structured content in LLM responses and applies syntax highlighting and formatting. The output rendering system (referenced in DeepWiki as Output Rendering and Formatting) identifies markdown code blocks, JSON, YAML, and other structured formats, then applies appropriate styling and indentation. The Lipgloss library provides terminal styling, and the system uses language detection to apply syntax-appropriate formatting.

Mods implements an internal cache system (referenced in DeepWiki as Cache System) that stores responses to identical requests, enabling response reuse without re-querying the LLM. The cache key is derived from the combined prompt, model, and sampling parameters. When a request matches a cached entry, the cached response is returned immediately without API calls, reducing latency and costs.

Builds a terminal user interface using the Bubble Tea framework (charmbracelet/bubbletea) that renders LLM responses in real-time as tokens arrive from the provider. The UI model (defined in mods.go) handles state transitions between input, streaming, and output modes, manages cursor positioning, and applies terminal-aware styling based on detected capabilities (color support, width). Streaming tokens are piped through a message context handler that buffers partial tokens and triggers UI updates via Bubble Tea's event loop.

Persists conversation history to a SQLite database (db.go) that stores messages with metadata (role, timestamp, model, provider). The conversation management system (Conversation struct in mods.go) loads prior messages when the --continue flag is used, appending them to the current request context. Messages are stored with full content and metadata, enabling conversation replay, context injection for multi-turn interactions, and audit trails of LLM interactions.

Detects whether input and output are connected to a terminal (isInputTTY, isOutputTTY in main.go) and adapts behavior accordingly: interactive mode with Bubble Tea UI when both are TTY, non-interactive mode with plain text output when piped. Supports reading prompts from stdin, command-line arguments, or file redirection, and writes responses to stdout for piping to other commands. This enables mods to function both as an interactive CLI tool and as a composable Unix filter.

Supports message roles (system, user, assistant) that are injected into LLM requests to control behavior and context. The message context handler (stream.go) formats messages with role metadata, enabling system prompts to define behavior, user messages to provide input, and assistant messages to provide examples or prior responses. Roles are passed to the provider client which formats them according to provider-specific conventions (OpenAI's role field, Anthropic's Human/Assistant tags).

Provides format control flags (--format, --no-markdown) that determine how LLM output is rendered. The output rendering system (in mods.go and UI layer) applies syntax highlighting based on detected code blocks, wraps text to terminal width, and optionally strips markdown formatting. Format detection is based on content analysis (presence of markdown syntax, code fences) and explicit user flags, enabling both automatic formatting and manual override.

Resolves model identifiers (e.g., 'gpt-4o', 'claude-3.5-sonnet') to provider-specific model names and endpoints via a model registry. The resolution logic (in startCompletionCmd) matches requested models to available providers, applies fallback logic if the primary provider doesn't support the model, and initializes the appropriate provider client. Model resolution happens at request time and includes validation of model availability and provider configuration.

Integrates with the MCP protocol to enable LLMs to call external tools and functions. The MCP integration layer (referenced in configuration system) allows mods to expose tools to the LLM, handle tool invocation requests, and return results back to the LLM for further processing. Tools are registered via MCP configuration, and the system handles the request-response cycle for tool calls.

Exposes LLM sampling parameters (temperature, top_p, top_k, max_tokens) via CLI flags and configuration, enabling users to control response variability and length. These parameters are passed to the provider client during initialization and forwarded to the LLM API. Temperature controls randomness (0 = deterministic, 1+ = creative), top_p/top_k control nucleus/top-k sampling, and max_tokens limits response length.