# charmbracelet/mods

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/charmbracelet-mods).**

4,476 stars · 237 forks · Go · mit

## Links

- GitHub: https://github.com/charmbracelet/mods
- awesome-repositories: https://awesome-repositories.com/repository/charmbracelet-mods.md

## Description

Mods is a terminal-based AI client that sends prompts to large language models and streams responses back to the command line. It functions as a multi-provider AI gateway, routing queries to OpenAI, Cohere, Groq, Gemini, and local endpoints, and includes a conversation history manager that saves, caches, branches, and resumes text-based interactions. The tool also operates as a Model Context Protocol client, connecting to external MCP servers via stdio, SSE, or HTTP to extend model capabilities with specialized tools and data.

The project distinguishes itself through a config-driven provider router that selects AI providers and models at runtime based on a YAML configuration file, and a system prompt persona manager that loads named role definitions to shape model behavior. It includes automatic retry with backoff for rate-limit and transient server errors, a file-based conversation store for persisting multi-turn dialogues, and a shell pipe input adapter that accepts piped stdin, file URLs, or direct arguments as prompt input. A streaming JSON-RPC gateway handles authentication, rate limiting, and response parsing for multiple backends, while a Markdown response formatter instructs the LLM to return structured output for terminal display.

The broader capability surface includes conversation management via CLI commands to list, show, continue, and delete saved interactions, as well as interactive prompt editing and the ability to format command output with AI. Users can configure generation parameters like model, temperature, and max tokens, define custom system prompts and personas, and manage conversation history with local storage. The tool also supports loading content from URLs or local files, streaming responses incrementally, and applying custom prompt prefixes to steer model behavior.

Configuration is managed through a YAML file that can be edited directly, with settings for provider and model selection, generation parameters, and system prompt definitions.

## Tags

### Artificial Intelligence & ML

- [Language Model Querying](https://awesome-repositories.com/f/artificial-intelligence-ml/language-model-querying.md) — Sends text or file content to an AI model and returns the generated response directly in the command line. ([source](https://github.com/charmbracelet/mods/blob/main/config.go))
- [Multi-turn Interaction Managers](https://awesome-repositories.com/f/artificial-intelligence-ml/agentic-systems-frameworks/conversational-voice-interaction/conversational-ai-agents/conversational-turn-detection/multi-turn-interaction-managers.md) — Maintains a history of user and assistant messages so subsequent queries can reference prior context. ([source](https://github.com/charmbracelet/mods/blob/main/messages_test.go))
- [Prompt Persona Definitions](https://awesome-repositories.com/f/artificial-intelligence-ml/agentic-systems-frameworks/integration-deployment/agent-frameworks/configuration-and-specifications/agent-persona-definitions/persona-assignments/prompt-persona-definitions.md) — Loads predefined instruction sets or character profiles that shape how the LLM interprets input. ([source](https://github.com/charmbracelet/mods#readme))
- [Provider Switching](https://awesome-repositories.com/f/artificial-intelligence-ml/agentic-systems-frameworks/model-integration-serving/model-integration-interfaces/ai-integration-apis/openai-compatible-apis/provider-switching.md) — Connect to OpenAI, Azure OpenAI, Cohere, Groq, Gemini, or any OpenAI-compatible endpoint by setting the corresponding API key. ([source](https://github.com/charmbracelet/mods#readme))
- [MCP Server Connections](https://awesome-repositories.com/f/artificial-intelligence-ml/agentic-systems-frameworks/model-integration-serving/model-integration-interfaces/model-context-protocol/mcp-server-management/mcp-server-connections.md) — Create and initialize a client for a server using stdio, SSE, or HTTP transport. ([source](https://github.com/charmbracelet/mods/blob/main/mcp.go))
- [AI Gateways](https://awesome-repositories.com/f/artificial-intelligence-ml/ai-gateways.md) — A command-line gateway that routes queries to OpenAI, Cohere, Groq, Gemini, and local endpoints.
- [Direct Model Queries](https://awesome-repositories.com/f/artificial-intelligence-ml/ai-model-integrations/direct-model-queries.md) — Sends text or file content as a prompt to a large language model and displays the generated response directly in the command line. ([source](https://github.com/charmbracelet/mods/blob/main/.goreleaser.yml))
- [Persona and Behavioral Instructions](https://awesome-repositories.com/f/artificial-intelligence-ml/ai-prompt-engineering-templates/automated-prompt-generation/persona-and-behavioral-instructions.md) — Defines named personas and behavioral roles that control how the AI model interprets and formats output.
- [MCP Client Implementations](https://awesome-repositories.com/f/artificial-intelligence-ml/artificial-intelligence-tooling/agent-and-tool-integrations/mcp-server-integrations/transport-layer-implementations/mcp-client-implementations.md) — Implements a Model Context Protocol client that connects to external servers via stdio, SSE, or HTTP to extend model capabilities with specialized tools.
- [System Prompt Management](https://awesome-repositories.com/f/artificial-intelligence-ml/artificial-intelligence-tooling/workflows-methodologies-and-prompts/system-prompt-management.md) — A configuration system that defines named personas and behavioral roles to control model output.
- [CLI Prompt Piping](https://awesome-repositories.com/f/artificial-intelligence-ml/cli-prompt-piping.md) — Feeds piped input from other commands or file contents into an AI model for processing and response generation. ([source](https://github.com/charmbracelet/mods/blob/main/config_test.go))
- [Conversation History Management](https://awesome-repositories.com/f/artificial-intelligence-ml/context-management-tools/conversation-history-management.md) — Saves, lists, shows, and deletes past interactions with AI models for later review or continuation. ([source](https://github.com/charmbracelet/mods/blob/main/config.go))
- [Conversation Management Systems](https://awesome-repositories.com/f/artificial-intelligence-ml/conversation-management-systems.md) — Lists, shows, continues, and deletes saved conversations using dedicated command-line flags. ([source](https://github.com/charmbracelet/mods#readme))
- [Conversation State Persistence](https://awesome-repositories.com/f/artificial-intelligence-ml/conversation-state-management/conversation-state-persistence.md) — Saves each interaction locally with a title and SHA-1 identifier for later review or continuation. ([source](https://github.com/charmbracelet/mods#readme))
- [External Tool Integrations](https://awesome-repositories.com/f/artificial-intelligence-ml/external-service-integrations/external-knowledge-integrators/external-tool-integrations.md) — Connect to MCP servers to access additional tools and capabilities during AI interactions. ([source](https://github.com/charmbracelet/mods/blob/main/config.go))
- [Interactive AI Conversations](https://awesome-repositories.com/f/artificial-intelligence-ml/interactive-ai-conversations.md) — Resumes an earlier AI interaction from its saved state to extend the dialogue without starting over. ([source](https://github.com/charmbracelet/mods/blob/main/config.go))
- [LLM Response Streaming](https://awesome-repositories.com/f/artificial-intelligence-ml/llm-response-streaming.md) — Receives and displays model output token by token as it is generated, showing results before the full response completes. ([source](https://github.com/charmbracelet/mods/blob/main/mods.go))
- [LLM-Powered Shell Response Generators](https://awesome-repositories.com/f/artificial-intelligence-ml/llm-response-streaming/llm-powered-shell-response-generators.md) — Pipes text or file content into a large language model and returns the generated response directly in the command line. ([source](https://github.com/charmbracelet/mods/custom-properties))
- [Tool Call Executions](https://awesome-repositories.com/f/artificial-intelligence-ml/mcp-tool-connectors/tool-call-executions.md) — Call a tool on a named MCP server by passing JSON arguments and returning the result. ([source](https://github.com/charmbracelet/mods/blob/main/mcp.go))
- [System Instruction Personas](https://awesome-repositories.com/f/artificial-intelligence-ml/model-configuration/role-based-model-assignment/system-instruction-personas.md) — Loads named role definitions from configuration that prepend custom system prompts to every query, shaping model behavior without modifying user input.
- [Model Provider Configurations](https://awesome-repositories.com/f/artificial-intelligence-ml/model-provider-configurations.md) — Selects which API backend and model to use for a given query from multiple providers. ([source](https://github.com/charmbracelet/mods/blob/main/mods.go))
- [AI Query Input Loaders](https://awesome-repositories.com/f/artificial-intelligence-ml/agentic-systems-frameworks/integration-deployment/agentic-domains/agentic-web-browsing/url-content-fetchers/ai-query-input-loaders.md) — Fetch the body of an HTTP or HTTPS URL and use it as input for an AI query. ([source](https://github.com/charmbracelet/mods/blob/main/load.go))
- [Custom Prompt Editors](https://awesome-repositories.com/f/artificial-intelligence-ml/ai-prompt-configurations/custom-prompt-editors.md) — Stores reusable role definitions that set the system prompt, allowing users to apply consistent instructions across queries. ([source](https://github.com/charmbracelet/mods#readme))
- [Generation Parameter Configurations](https://awesome-repositories.com/f/artificial-intelligence-ml/generation-temperature-controls/generation-parameter-configurations.md) — Sets model, temperature, top-p, top-k, max tokens, retries, and proxy to control how the LLM generates responses. ([source](https://github.com/charmbracelet/mods#readme))
- [MCP Servers](https://awesome-repositories.com/f/artificial-intelligence-ml/mcp-servers.md) — Lists configured MCP servers and shows which ones are enabled. ([source](https://github.com/charmbracelet/mods/blob/main/mcp.go))
- [MCP Tool Retrievers](https://awesome-repositories.com/f/artificial-intelligence-ml/mcp-tool-connectors/mcp-tool-retrievers.md) — Connects to each enabled MCP server and prints the tools it exposes. ([source](https://github.com/charmbracelet/mods/blob/main/mcp.go))
- [Model Context Protocol Clients](https://awesome-repositories.com/f/artificial-intelligence-ml/model-context-protocol-clients.md) — Connects to external MCP servers via stdio, SSE, or HTTP to extend AI model capabilities with specialized tools.
- [Model Fallbacks](https://awesome-repositories.com/f/artificial-intelligence-ml/model-task-retries/model-fallbacks.md) — Switch to a configured fallback model when the primary model is unavailable or returns a 404. ([source](https://github.com/charmbracelet/mods/blob/main/mods_errors.go))
- [Prompt Prefixes](https://awesome-repositories.com/f/artificial-intelligence-ml/text-classification/prompt-customization/prompt-prefixes.md) — Prepends a fixed text to every query to steer the model's behavior without modifying the input. ([source](https://github.com/charmbracelet/mods/blob/main/mods.go))

### Networking & Communication

- [LLM Query Clients](https://awesome-repositories.com/f/networking-communication/dns-query-clients/encrypted-query-clients/llm-query-clients.md) — Queries large language models directly from the command line by piping text or files and streaming responses.
- [Streaming AI Gateways](https://awesome-repositories.com/f/networking-communication/json-rpc-implementations/streaming-ai-gateways.md) — Routes AI model requests through a streaming JSON-RPC interface that handles authentication, rate limiting, and response parsing for multiple backends.

### Data & Databases

- [File-Based Stores](https://awesome-repositories.com/f/data-databases/persistent-conversation-stores/file-based-stores.md) — Persists multi-turn conversation state as local JSON files keyed by SHA-1 hash, enabling save, resume, and branching of dialogues.
- [AI-Powered Formatting](https://awesome-repositories.com/f/data-databases/custom-reporting-engines/command-line-output-formatting/ai-powered-formatting.md) — Transforms raw terminal output into structured formats like Markdown or JSON using an LLM. ([source](https://github.com/charmbracelet/mods#readme))
- [LLM Response Renderers](https://awesome-repositories.com/f/data-databases/data-serialization-formats/data-formats/output-format-rendering/llm-response-renderers.md) — Asks the model to return output in Markdown and optionally applies syntax highlighting or raw printing. ([source](https://github.com/charmbracelet/mods#readme))

### Development Tools & Productivity

- [LLM Clients](https://awesome-repositories.com/f/development-tools-productivity/api-client-libraries/llm-clients.md) — An AI query tool that sends prompts to large language models and streams responses back to the terminal.
- [Prompt Editors](https://awesome-repositories.com/f/development-tools-productivity/human-in-the-loop-interfaces/interactive-prompts/prompt-editors.md) — Opens the current prompt in a text editor for modification before sending it to the AI model. ([source](https://github.com/charmbracelet/mods/blob/main/config.go))

### Testing & Quality Assurance

- [LLM-As-A-Judge Scoring](https://awesome-repositories.com/f/testing-quality-assurance/llm-as-a-judge-scoring.md) — Pipes text or file content as a prompt to a large language model and returns the generated response directly in the command line. ([source](https://github.com/charmbracelet/mods#readme))

### Web Development

- [AI Provider Routing](https://awesome-repositories.com/f/web-development/api-endpoint-configurations/service-endpoint-configurations/ai-provider-routing.md) — Send queries to OpenAI, Cohere, Groq, Gemini, or a local LocalAI endpoint based on configuration. ([source](https://github.com/charmbracelet/mods#readme))
- [Endpoint Aliases](https://awesome-repositories.com/f/web-development/api-endpoint-configurations/service-endpoint-configurations/ai-provider-routing/endpoint-aliases.md) — Define endpoints and aliases for various OpenAI-compatible APIs to switch between providers seamlessly. ([source](https://github.com/charmbracelet/mods/blob/main/config.go))
- [Provider-Agnostic LLM Routing](https://awesome-repositories.com/f/web-development/provider-agnostic-llm-routing.md) — Sends queries to different cloud and local AI providers and switches between them with a single configuration.
- [Markdown](https://awesome-repositories.com/f/web-development/response-formatting/markdown.md) — Asks the language model to structure its reply in Markdown for easier reading and further pipeline processing. ([source](https://github.com/charmbracelet/mods#readme))

### Part of an Awesome List

- [Theme and Behavior Customizations](https://awesome-repositories.com/f/awesome-lists/media/chat/visual-and-behavioral-configuration/theme-and-behavior-customizations.md) — Adjusts temperature, token limit, and stop sequences to control AI response style and length. ([source](https://github.com/charmbracelet/mods/blob/main/config.go))

### DevOps & Infrastructure

- [Server Error Retries](https://awesome-repositories.com/f/devops-infrastructure/api-service-management/api-resilience/request-retries/server-error-retries.md) — Re-attempt a request after a transient server-side failure, such as a 500 or 404 for a fallback model. ([source](https://github.com/charmbracelet/mods/blob/main/mods_errors.go))

### Programming Languages & Runtimes

- [Exponential Backoff Retries](https://awesome-repositories.com/f/programming-languages-runtimes/language-features-paradigms/concurrency-models/background-task-management/background-task-retry-policies/asynchronous-task-retries/exponential-backoff-retries.md) — Detects rate-limit and transient server errors (404, 500) and re-attempts the request with exponential backoff before falling back to an alternate model.

### Security & Cryptography

- [API Rate Limit Management](https://awesome-repositories.com/f/security-cryptography/request-size-limiters/request-limiters/request-throttling/client-request-quotas/api-rate-limit-management.md) — Automatically wait and resend a request when the API reports a rate-limit or overload error. ([source](https://github.com/charmbracelet/mods/blob/main/mods_errors.go))