Published 2025-11-12.
Last modified 2025-11-16.
Time to read: 7 minutes.
llm collection.
I have been using Claude CLI in Visual Studio Code. With Claude’s agentic support, this old programmer now has the strength of 10 young programmers, and the wisdom to know better. However, Claude has limits and is expensive, so I am looking for faster, cheaper, better alternatives.
LLMs are like wayward children
Most need constant babysitting or extreme preparation
Some are more difficult than others
MiniMax mini-agent is a very new program, only released 3 weeks ago, so it is not surprising that it has rough edges. However, mini-agent has much promise, and can deliver good value if used carefully.
Registration with MiniMax requires a password containing only alphanumeric characters. This was an unnecessary annoyance.
Get a free MiniMax API key from platform.minimax.io
and sign up for a
payment plan.
Installation
The following incantation results in a permanent installation:
$ uv tool install git+https://github.com/MiniMax-AI/Mini-Agent.git
The above gives you a new command: mini-agent.
If you just want to try out the tool, use uvx instead:
$ uvx git+https://github.com/MiniMax-AI/Mini-Agent.git
The above immediately runs the program but does not give you the mini-agent command.
Configuration
Make a quick initial setup by typing:
$ curl -fsSL https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.sh | bash ╔════════════════════════════════════════════════╗ ║ Mini Agent Configuration Setup ║ ╚════════════════════════════════════════════════╝ [1/2] Creating configuration directory... ✓ Created: /home/mslinn/.mini-agent/config [2/2] Downloading configuration files... ✓ Downloaded: config.yaml ✓ Downloaded: mcp.json ✓ Downloaded: system_prompt.md ✓ Configuration files ready ╔════════════════════════════════════════════════╗ ║ Setup Complete! ✨ ║ ╚════════════════════════════════════════════════╝ Configuration files location: /home/mslinn/.mini-agent/config Files: 📄 config.yaml 📄 mcp.json 📄 system_prompt.md
I edited ~/.mini-agent/config/config.yaml and pasted my MiniMax
API key into it.
Command Line Syntax
$ mini-agent # Use current directory
$ mini-agent --workspace /path/to/project # Specify workspace
$ mini-agent --help # Show help
Using mini-agent
$ cd $work/myproject
$ mini-agent ✅ LLM retry mechanism enabled (max 3 retries) ✅ Loaded Bash tool ✅ Loaded Bash Output tool ✅ Loaded Bash Kill tool Loading Claude Skills... ✅ Discovered 15 Claude Skills ✅ Loaded Skill tool (get_skill) Loading MCP tools... Skipping disabled server: minimax_search Skipping disabled server: memory Total MCP tools loaded: 0 ⚠️ No available MCP tools found ✅ Loaded file operation tools (workspace: /mnt/f/work/myproject) ✅ Loaded session note tool ✅ Loaded system prompt (from: /home/mslinn/.mini-agent/config/system_prompt.md) ✅ Injected 15 skills metadata into system prompt ╔══════════════════════════════════════════════════════════╗ ║ 🤖 Mini Agent - Multi-turn Interactive Session ║ ╚══════════════════════════════════════════════════════════╝ ┌──────────────────────────────────────────────────────────┐ │ Session Info │ ├──────────────────────────────────────────────────────────┤ │ Model: MiniMax-M2 │ │ Workspace: /tmp/miniagent │ │ Message History: 1 messages │ │ Available Tools: 8 tools │ └──────────────────────────────────────────────────────────┘ Type /help for help, /exit to quit
This is the mini-agent CLI help message:
You › /help Available Commands: /help - Show this help message /clear - Clear session history (keep system prompt) /history - Show current session message count /stats - Show session statistics /exit - Exit program (also: exit, quit, q) Keyboard Shortcuts: Ctrl+U - Clear current input line Ctrl+L - Clear screen Ctrl+J - Insert newline (also Ctrl+Enter) Tab - Auto-complete commands ↑/↓ - Browse command history → - Accept auto-suggestion Usage: - Enter your task directly, Agent will help you complete it - Agent remembers all conversation content in this session - Use /clear to start a new session - Press Enter to submit your message - Use Ctrl+J to insert line breaks within your message
The system prompt is stored in ~/.mini-agent/config/system_prompt.md.
It looks like this when rendered:
You are Mini-Agent, a versatile AI assistant powered by MiniMax, capable of executing complex tasks through a rich toolset and specialized skills.
Core Capabilities
1. Basic Tools
- File Operations: Read, write, edit files with full path support
- Bash Execution: Run commands, manage git, packages, and system operations
- MCP Tools: Access additional tools from configured MCP servers
2. Specialized Skills
You have access to specialized skills that provide expert guidance and capabilities for specific tasks.
Skills are loaded dynamically using Progressive Disclosure:
- Level 1 (Metadata): You see skill names and descriptions (below) at startup
- Level 2 (Full Content): Load a skill’s complete guidance using
get_skill(skill_name) - Level 3+ (Resources): Skills may reference additional files and scripts as needed
How to Use Skills:
- Check the metadata below to identify relevant skills for your task
- Call
get_skill(skill_name)to load the full guidance - Follow the skill’s instructions and use appropriate tools (bash, file operations, etc.)
Important Notes:
- Skills provide expert patterns and procedural knowledge
- For Python skills (pdf, pptx, docx, xlsx, canvas-design, algorithmic-art): Setup Python environment FIRST (see Python Environment Management below)
- Skills may reference scripts and resources - use bash or read_file to access them
{SKILLS_METADATA}
Working Guidelines
Task Execution
- Analyze the request and identify if a skill can help
- Break down complex tasks into clear, executable steps
- Use skills when appropriate for specialized guidance
- Execute tools systematically and check results
- Report progress and any issues encountered
File Operations
- Use absolute paths or workspace-relative paths
- Verify file existence before reading/editing
- Create parent directories before writing files
- Handle errors gracefully with clear messages
Bash Commands
- Explain destructive operations before execution
- Check command outputs for errors
- Use appropriate error handling
- Prefer specialized tools over raw commands when available
Python Environment Management
CRITICAL - Use uv for all Python operations. Before executing Python code:
- Check/create venv:
if [ ! -d .venv ]; then uv venv; fi - Install packages:
uv pip install <package> - Run scripts:
uv run python script.py - If uv missing:
curl -LsSf https://astral.sh/uv/install.sh | sh
Python-based skills: pdf, pptx, docx, xlsx, canvas-design, algorithmic-art
Communication
- Be concise but thorough in responses
- Explain your approach before tool execution
- Report errors with context and solutions
- Summarize accomplishments when complete
Best Practices
- Don’t guess - use tools to discover missing information
- Be proactive - infer intent and take reasonable actions
- Stay focused - stop when the task is fulfilled
- Use skills - leverage specialized knowledge when relevant
Workspace Context
You are working in a workspace directory. All operations are relative to this context unless absolute paths are specified.
Gemini Told Me This
You cannot directly increase the hardcoded maximum context window size of a specific MiniMax model, as this limit is defined by the underlying model architecture (e.g., MiniMax M2 has a 204K token limit, M1 has a 1M token limit). Instead, you can use specific techniques and agentic workflows provided by the MiniMax platform to manage and extend the effective context during long or complex tasks. Techniques to Manage and Extend Context
For models like MiniMax M2, the key method is to enable reasoning_split=True when using the OpenAI-compatible API, or by natively including <think>…</think> blocks in your messages when using the Anthropic-compatible API. This ensures the agent’s internal reasoning chain is explicitly passed back into the next prompt, maintaining state and improving performance across multiple turns.
The MiniMax Agent interface allows for creating “branch sessions” or new sessions. If an original conversation is nearing its token limit, you can start a new branch to continue the project in a fresh context, avoiding “lost in the middle” problems associated with overly long contexts.
The MiniMax agent uses internal methods like code output compression and optimized browser handling to manage token usage and keep the context lean.
For handling lots of information (like large documentation or a codebase), the agent uses RAG processes and “Model Context Protocol” (MCP) servers to retrieve relevant information as needed, rather than loading everything into the main context window at once. This emulates a form of long-term memory. Model Selection: If your work consistently requires a massive context window, ensure you are using a MiniMax model specifically designed for it, such as MiniMax-Text-01 (4 million tokens inference) or MiniMax-M1 (1 million tokens).
For practical implementation and configuration, refer to the MiniMax Agent GitHub documentation or the MiniMax Agent Changelog.
Impressions Working with Mini-Agent
I paid in USD because MiniMax offered a much higher price in Canadian dollars; an unfavorable exchange rate was used. Anthropic did not give me a choice of currencies when I subscribed to Claude Pro.
Mini-agent is direct and to the point. Subscribers get a fresh service ration every 5 hours.
Mini-agent can often diagnose problems quickly, but it does not pay close attention to instructions, so it can wander off into the weeds and start to flail. Claude is much better at doing what you tell it. You need to carefully watch mini-agent work. Mini-agent does not appear to have a mean streak the way that Grok does, though.
Mini-agent lacks common sense, something that Claude has in abundance. For example, when discussing changes to a codebase, it does not read the documentation and the code unless explicitly told to do so. As a result, it either asks a lot of stupid questions or it plows ahead, wreaking chaos left and right. At first, it seemed like most of the words I wrote as instructions to mini-agent were to keep it tightly leashed. This was a huge waste of time, because if the little bugger gets away on you, your only option it to press CTRL+C and start over, wasting money and time.
However, if you spend time carefully setting up ground rules (as shown in Ruby Gems For Jekyll Plugin below), mini-agent works much more smoothly.
Each time mini-agent asks several questions at once (and it does this frequently), mini-agent hangs and you lose the entire session. You must tell mini-agent to ask questions one at a time. Unfortunately, it immediately forgets and asks several questions anyway, but if you remind it, mini-agent will apologize, present the first question again, get the answer, and forget all the other questions that it had. Sigh.
Claude CLI has an annoying problem of creating Git locks in the project being worked on and forgetting about them. Mini-agent thankfully does not have this issue.
Mini-agent auto-compacts every 80,000 tokens, which takes about a minute. Claude does not need to compact as often.
There is no way to interrupt the LLM once it starts. I requested the feature.
It creates a file for its own purposes called .agent_memory.json
that belongs in .gitignore.
I miss the Claude TUI status line that I made. That gave me a clear idea of when the LLM was struggling.
While Claude offers a nice real-time display of how much of your daily/weekly/monthly budget has been spent, MiniMax does not offer any such insight.
MiniMax-M2 was supposed to be good at debugging complex issues, but I found it got confused over trivial concepts. For example, a Golang program I was working on needed to store files and directories internally so they could be recreated at runtime. I was unable to explain the concept of embedded file systems, but Claude understood immediately. Claude is much better at debugging.
Both MiniMax-M2 and Claude favor logic over data structures. This is likely due to not actually conceptualizing what they is doing at a higher level. Skilled programmers need not fear for their continued usefulness.
Working Example
After several sessions in which I got a feeling for the behavior of mini-agent, I decided to try a small bug fix that involves two projects. This is something I had originally tried to do with Google Gemini Code Assist, but learned that Google Gemini Code Assist cannot handle more than one code base at a time.
I always build systems from components. Each component gets its own Git project. An agentic assistant that cannot deal with more than a single project at once is nearly useless to me.
Both mini-agent and Claude CLI have no problems with multiple related projects.
About the Projects
I have published dozens of Ruby gems for Jekyll Plugins using my Jekyll Plugin Support gem. The Flexible Include plugin is one of my most popular plugins.
I was implementing a new feature, and realized that some logic should be moved from the framework to the plugin.
The instructions I gave mini-agent are shown in the next section.
Ruby Gems For Jekyll Plugin
These LLM directives are now part of the Jekyll Plugin Support Git project. Everyone who clones the framework or works on a plugin built with that framework can use the directives with any agentic programming agent to create or maintain these projects.
# Jekyll Plugin Support Instructions for Claude ## General Instructions - Read `.claude/RUBY_STANDARDS.md` in this directory so you can learn about Ruby coding instructions. - Do not use emojis in user dialog or documentation. - Do not use superlatives; instead, be strictly factual. - Do not ask the user several questions at once. Instead, make a list of questions and ask your questions one at a time. - Make no assumptions. Ask the user about every ambiguity or corner case, and suggest a better way if there is one. Think about your questions before you ask them; can it be answered by merely considering a broader context? If so, make that a provisional assumption and ask for confirmation. - If you need to write documentation, place the file in the `docs/` directory. - Before running every git command, check if `.git/index.lock` exists, and delete it using `sudo` if so. - Git projects have environment variables that point to their directories. Some examples: - `$jekyll_plugin_support` points to the directory containing the `jekyll_plugin_support` Git project. - `$jekyll_href` points to the directory containing the `jekyll_href` Git project that defines the `href` plugin. - `$jekyll_pre` points to the directory containing the `jekyll_pre` Git project that defines the `pre` plugin. - `$jekyll_img` points to the directory containing the `jekyll_img` Git project that defines the `img` plugin. - `$jekyll_flexible_include_plugin` points to the `jekyll_flexible_include_plugin` Git project that contains the directory containing the `flexible_include` plugin. ## Requirements for Done The following must be completed before your work can be considered to be done. - Update documentation with changes - Unit tests must pass - Linters for all languages (bash, Ruby, Markdown, etc) must succeed. - Unit tests must pass. - Update `README.md` for user-visible changes only. - Update `CHANGES.md` for programmer-visible changes, described at a high level. - Update `.claude/PROGRESS.md`. - Only then `git push` with a message and commit. ## DO THIS NOW Read `.claude/FUTURE.md` and execute instructions in the following section: Rework Windows Environment Variable Expansion
# Future Work Do not perform any of the following without specific authorization. ## Rework Windows Environment Variable Expansion Many shells, for example Bash, denote environment variable references (env vars) by prefixing them with a dollar sign ($). Windows environment variables are denoted differently, by enclosing them within percents (%). In JPS, the current implementation of environment expansion is defined in the `JekyllPluginHelper.expand_env` method in `$jekyll_plugin_support/lib/helper/jekyll_plugin_helper_class.rb`. This method currently calls `JekyllPluginHelper.expand_env`, which in turn calls `JekyllPluginHelper.env_var_expand_bash` and `JekyllPluginHelper.env_var_expand_windows`. This is problematic because websites often contain text strings that contain pairs of percents that should not be expanded because they do not correspond to environment variables (for example "blah%some_text%more text"). To correct the problem, `expand_env` should never call `env_var_expand_windows`, and should instead merely return the result of calling `env_var_expand_bash`. This means that the `use_wslvar` parameter is not required by this method or the methods that it calls, and the method signatures should be simplified. `JekyllPluginHelper.env_var_expand_windows` will be called by JPS plugins when required, so that method it must remain intact. Currently the only Jekyll plugin that needs to call `JekyllPluginHelper.env_var_expand_windows` is `jekyll_flexible_include_plugin`. That plugin only needs to call `JekyllPluginHelper.env_var_expand_windows` to expand the `file` parameter, exactly as shown in `$jekyll_flexible_include_plugin/demo/index.html`. Modify `$jekyll_flexible_include_plugin/lib/flexible_include_private_methods.rb` so the `@filename` parameter is expanded using both `JekyllPluginHelper.env_var_expand_bash` and `JekyllPluginHelper.env_var_expand_windows`. I already updated `CHANGELOG.md` so you do not have to. Describe your plan and obtain approval before starting.
# Progress
# Ruby Programming Standards
Jekyll is a Ruby gem that creates static websites.
This project (`jekyll_plugin_support`) is a framework for writing and testing
[Jekyll](https://jekyllrb.com/) plugins in the Ruby language. These plugins
share common coding standards and debugging techniques. We shall refer to
`jekyll_plugin_support` as `JPS` for convenience, and plugins created from the
JPS framework as `JPS plugins`.
## General
- Write using Ruby 3.4.7 features and recommended syntax.
- Follow the existing coding style.
- Use multiline strings whenever possible using squiggly heredocs (`<<~IDENTIFIER`).
- Before making any changes, tell the user a high-level explanation
- If requested, show detailed changes.
- Proceed after the user approves the changes.
## Comments
- Preserve existing comments and formatting.
- Only write new comments when they are non-obvious.
- Assume the reader knows the Ruby language, so do not explain common Ruby
coding techniques.
- Assume the reader is new to writing Jekyll plugins and is unfamiliar with
`jekyll_plugin_support`.
## Unit Tests
- Write unit tests using RSpec for non-trivial functionality.
See the `spec` subdirectory for examples of existing tests.
- Configuration for unit tests is provided in the top-level `_config.yml` in this project.
## Demo Project
Many features cannot be easily tested using RSpec. However, all features should
be testable by making Jekyll web pages in the Jekyll website in the `demo`
subdirectory and running the demo.
- Use the scripts in the `bin` directory to test functionality in a live setup.
- All Jekyll plugins based on `jekyll_plugin_support` should include a `demo`
subdirectory.
- Configuration for the `demo` Jekyll website is provided in `_config.yml` in
that subdirectory.
- The `demo` project in the `jekyll_plugin_support` project contains examples of
how important JPS plugins are used.
### Demo Project Configuration
- The `Gemfile` in the `demo` subdirectory can be used for debugging plugins
based on `jekyll_plugin_support`.
- Each of the `gem` lines can include an optional `path` argument, like
`path: jekyll_flexible_include`. Here is an example:
```ruby
jekyll_flexible_include = ENV.fetch('jekyll_flexible_include', nil)
group :jekyll_plugins do
gem 'jekyll_flexible_include', path: jekyll_flexible_include
end
```
Do It Now
Now all I had to type was:
Read and execute .claude/CLAUDE.md
After carefully preparing several very detailed files, the work was done within 20 minutes. I did some housework while waiting. The new release was solid. Life was good.
The time I spent preparing for this simple bug fix will benefit me each time in the future that another change needs to be made.
