Minion is a purpose-built, single-file coding agent designed to address context bloat in Large Language Model (LLM) interactions, particularly for self-hosted and local models. It targets developers and power users seeking efficient, low-overhead AI assistance for tasks like reading, writing, editing code, and executing shell commands, without the significant token costs and latency associated with feature-rich agent frameworks. Minion prioritizes speed and intelligence by minimizing prompt size, ensuring the LLM's most capable context window is used effectively.

How It Works

Minion employs a minimalist architecture, encapsulated within a single Python file (~3400 lines), to facilitate understanding and modification. It connects to any OpenAI-compatible LLM endpoint, including local setups like llama.cpp, vLLM, or SGLang, as well as remote APIs. The agent drastically reduces context window usage, maintaining prompts around 625 tokens per turn, significantly less than typical agents that consume tens of thousands of tokens before any user input. This approach leverages the LLM's fastest and most attentive context, optimizing performance and cost. It includes a fallback mechanism for models lacking native tool-calling support, parsing tool calls from text, and gracefully handles streaming responses, including separate reasoning content.

Quick Start & Requirements

• Installation:
  • Install the OpenAI Python client: pip install openai
  • Install Minion from source for command-line use: pip install -e .
• Prerequisites: An OpenAI-compatible LLM endpoint (local or remote).
• Configuration: Set environment variables such as MINION_BASE_URL, MINION_MODEL, and MINION_API_KEY (or use a ~/.env file).
• Run: python minion.py or minion (after installation).

Highlighted Details

• Minimal Context: Maintains prompts around 625 tokens, optimizing speed and cost for local LLMs.
• Single-File Design: Simplifies understanding, modification, and debugging.
• Flexible Endpoints: Supports local (llama.cpp, vLLM, SGLang) and remote OpenAI-compatible APIs.
• Session Persistence: Automatically saves conversations to JSON files, allowing seamless resume functionality.
• Risk-Based Approval: Prompts for confirmation on potentially destructive shell commands, with configurable approval levels.
• Graceful Degradation: Falls back to text parsing for tool calls if native support is absent and handles malformed streams.

Maintenance & Community

The project is maintained by Sentdex. Specific community channels (like Discord or Slack) or detailed roadmap information are not explicitly detailed in the provided README.

Licensing & Compatibility

Minion is released under the MIT License, which permits broad use, including commercial applications, with minimal restrictions.

Limitations & Caveats

Minion requires a pre-configured OpenAI-compatible LLM endpoint to function. While designed for robustness, its fallback mechanisms for tool-calling and stream handling may encounter edge cases with highly non-standard model outputs. The lack of explicit community support channels might impact collaborative development or rapid issue resolution.