$ show charmbracelet/mods
Mods is a CLI tool that pipes command output to large language models (LLMs) for AI-powered processing. It reads stdin, prepends a user prompt, sends the combined text to an LLM (OpenAI, Anthropic, Cohere, Google, Ollama, etc.), and streams the response to stdout. The architecture is a single Go binary using Bubble Tea for TUI (spinner, viewport) and a plugin-like provider system via the `internal/stream` interface. Key entry points are `main.go` (cobra CLI) and `mods.go` (Bubble Tea model). Data flows: stdin -> prompt assembly -> provider API call -> streaming output -> optional conversation caching (SQLite + gob files). External dependencies include multiple AI SDKs, Bubble Tea, Glamour for Markdown rendering, and SQLite for conversation storage. The repository is now archived as of March 2026, with the team focusing on a successor tool (Crush). Despite being archived, the codebase is well-structured, cleanly separated, and demonstrates strong Go engineering practices with a focus on testability and modularity.
The LLM identified 5 files worth highlighting for reuse:
Defines the `Client` and `Stream` interfaces that abstract LLM provider interactions. The `Client` interface has a single `Request` method returning a `Stream`, which provides `Next()`, `Current()`, `Close()`, `Err()`, `Messages()`, and `CallTools()`. This clean abstraction allows adding new providers (OpenAI, Anthropic, Cohere, etc.) without modifying core logic. The `CallTool` helper function standardizes tool call handling across providers. This package is highly reusable for any Go project needing a generic streaming LLM client.
Provides a generic, file-based cache using gob encoding. Supports typed caches (`Cache[T]`) with read, write, and delete operations. The `ExpiringCache` variant adds time-based expiration by encoding the expiry timestamp in the filename. The conversation cache (`convo.go`) builds on this to store `[]proto.Message` with backward compatibility for older message formats (without tool calls). This is a clean, reusable caching pattern that can be extracted for any project needing simple file-based persistence with optional expiration.
Defines the shared data structures (`Message`, `Chunk`, `Request`, `ToolCall`, `ToolCallStatus`) used across all providers and the main application. This package acts as a canonical protocol layer, decoupling provider implementations from the core logic. The `Conversation` type provides a `String()` method for rendering conversations. This is a textbook example of a shared internal protocol package that could be reused in any multi-provider LLM application.
Implements the `stream.Client` interface for OpenAI-compatible APIs. Handles authentication, proxy configuration, Azure AD support, and streaming via the official OpenAI Go SDK. The `Stream` type manages tool calls, message accumulation, and reconnection for continued streaming. This is a clean adapter pattern that demonstrates how to wrap a third-party SDK behind a common interface, making it easy to swap providers.
Implements the `stream.Client` interface for Anthropic's Claude API. Handles the Anthropic-specific message format (system vs user messages, tool use blocks) and streaming via SSE. The `Stream` type correctly maps Anthropic's event types to the common `proto.Chunk` format and manages tool call results. This is another clean adapter implementation that demonstrates how to handle a different API structure behind the same interface.