MinionCodeAgent

An enhanced AI code assistant built on the Minion framework, pre-configured with rich development tools, optimized for code development tasks.

Features

🤖 Intelligent Code Assistant: Pre-configured AI agent designed for programming tasks
🔧 Rich Toolset: Automatically includes 12+ tools for file operations, command execution, web search, etc.
⚡ Ready to Use: One-line creation, no complex configuration needed
📝 Conversation History: Built-in conversation history tracking and management
🎯 Optimized Prompts: System prompts optimized for code development tasks
🛡️ Security by Design: Built-in security checks to prevent dangerous operations
🔌 ACP Protocol Support: Seamless integration with ACP clients like Zed editor

Installation

Option 1: Install from source (recommended for development)

# Clone the dependency repository
git clone https://github.com/femto/minion

# Clone this repository
git clone https://github.com/femto/minion-code

# Enter the directory
cd minion-code

# Install minion dependency
pip install -e ../minion

# Install minion-code
pip install -e .

In this case, MINION_ROOT is located at ../minion

Option 2: Direct installation (recommended for general use)

# Clone this repository
git clone https://github.com/femto/minion-code
cd minion-code

# Install dependencies
pip install minionx

# Install minion-code
pip install -e .

In this case, MINION_ROOT is located at the current startup location

On startup, the actual path of MINION_ROOT will be displayed:

2025-11-13 12:21:48.042 | INFO     | minion.const:get_minion_root:44 - MINION_ROOT set to: <some_path>

LLM Configuration

Please refer to https://github.com/femto/minion?tab=readme-ov-file#get-started

Make sure the config file is in MINION_ROOT/config/config.yaml or ~/.minion/config.yaml

Quick Start

CLI Usage

# Basic usage
mcode

# Specify working directory
mcode --dir /path/to/project

# Specify LLM model
mcode --model gpt-4o
mcode --model claude-3-5-sonnet

# Enable verbose output
mcode --verbose

# Load additional tools using MCP config file
mcode --config mcp.json

# Combined usage
mcode --dir /path/to/project --model gpt-4o --config mcp.json --verbose

Model Configuration

Configure the default LLM model used by minion-code:

# View current default model
mcode model

# Set default model (saved to ~/.minion/minion-code.json)
mcode model gpt-4o
mcode model claude-3-5-sonnet

# Clear default model (use built-in default)
mcode model --clear

Model Priority:

CLI --model argument (highest priority)
Config file ~/.minion/minion-code.json
Built-in default (lowest priority)

ACP Protocol Support

MinionCodeAgent supports the ACP (Agent Communication Protocol) protocol, enabling integration with ACP-compatible clients like Zed editor.

# Start ACP server (stdio mode)
mcode acp

# Specify working directory
mcode acp --dir /path/to/project

# Specify LLM model
mcode acp --model gpt-4o

# Enable verbose logging
mcode acp --verbose

# Skip tool permission prompts (auto-allow all tools)
mcode acp --dangerously-skip-permissions

# Combined usage
mcode acp --dir /path/to/project --model claude-3-5-sonnet --verbose

Using with Zed Editor

Add the following to Zed's settings.json:

{
  "agent_servers": {
    
    "minion-code": {
      "type": "custom",
      "command": "/path/to/mcode",
      "args": [
        "acp"
      ],
      "env": {}
    }
  }
}

Permission Management

In ACP mode, tool calls will request user permission:

Allow once: Allow this time only
Always allow: Permanently allow this tool (saved to ~/.minion/sessions/)
Reject: Deny execution

Programming Interface

import asyncio
from minion_code import MinionCodeAgent

async def main():
    # Create AI code assistant with all tools auto-configured
    agent = await MinionCodeAgent.create(
        name="My Code Assistant",
        llm="gpt-4.1"
    )

    # Chat with the AI assistant
    response = await agent.run_async("List files in current directory")
    print(response.answer)

    response = await agent.run_async("Read the README.md file")
    print(response.answer)

asyncio.run(main())

Custom Configuration

# Custom system prompt and working directory
agent = await MinionCodeAgent.create(
    name="Python Expert",
    llm="gpt-4.1",
    system_prompt="You are a specialized Python developer assistant.",
    workdir="/path/to/project",
    additional_tools=[MyCustomTool()]
)

View Available Tools

# Print tools summary
agent.print_tools_summary()

# Get tools info
tools_info = agent.get_tools_info()
for tool in tools_info:
    print(f"{tool['name']}: {tool['description']}")

Built-in Tools

MinionCodeAgent automatically includes the following tool categories:

📁 File and Directory Tools

FileReadTool: Read file contents
FileWriteTool: Write files
GrepTool: Search text in files
GlobTool: File pattern matching
LsTool: List directory contents

💻 System and Execution Tools

BashTool: Execute shell commands
PythonInterpreterTool: Execute Python code

🌐 Network and Search Tools

WebSearchTool: Web search
WikipediaSearchTool: Wikipedia search
VisitWebpageTool: Visit webpages

🔧 Other Tools

UserInputTool: User input
TodoWriteTool: Task management write
TodoReadTool: Task management read

MCP Tool Integration

MinionCodeAgent supports loading additional tools via MCP (Model Context Protocol) configuration files.

MCP Configuration File Format

Create a JSON configuration file (e.g., mcp.json):

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    },
    "filesystem": {
      "command": "uvx",
      "args": ["mcp-server-filesystem", "/tmp"],
      "disabled": true,
      "autoApprove": ["read_file", "list_directory"]
    },
    "git": {
      "command": "uvx", 
      "args": ["mcp-server-git"],
      "disabled": false,
      "autoApprove": ["git_status", "git_log"]
    }
  }
}

Configuration Options

command: Command to start the MCP server
args: List of command arguments
env: Environment variables (optional)
disabled: Whether to disable this server (default: false)
autoApprove: List of tool names to auto-approve (optional)

Using MCP Configuration

# Use MCP config file
minion-code --config examples/mcp_config.json

# View loaded tools (including MCP tools)
# In CLI, type: tools

Using MCP Tools in Programming Interface

from minion_code.utils.mcp_loader import load_mcp_tools
from pathlib import Path

async def main():
    # Load MCP tools
    mcp_tools = await load_mcp_tools(Path("mcp.json"))

    # Create agent with MCP tools
    agent = await MinionCodeAgent.create(
        name="Enhanced Assistant",
        llm="gpt-4o-mini",
        additional_tools=mcp_tools
    )

Conversation History Management

# Get conversation history
history = agent.get_conversation_history()
for entry in history:
    print(f"User: {entry['user_message']}")
    print(f"Agent: {entry['agent_response']}")

# Clear history
agent.clear_conversation_history()

Comparison with Original Implementation

Before (Complex manual configuration)

# Need to manually import and configure all tools
from minion_code.tools import (
    FileReadTool, FileWriteTool, BashTool,
    GrepTool, GlobTool, LsTool,
    PythonInterpreterTool, WebSearchTool,
    # ... more tools
)

# Manually create tool instances
custom_tools = [
    FileReadTool(),
    FileWriteTool(),
    BashTool(),
    # ... more tool configuration
]

# Manually set system prompt
SYSTEM_PROMPT = "You are a coding agent..."

# Create agent (~50 lines of code)
agent = await CodeAgent.create(
    name="Minion Code Assistant",
    llm="gpt-4o-mini",
    system_prompt=SYSTEM_PROMPT,
    tools=custom_tools,
)

Now (Using MinionCodeAgent)

# One line of code completes all setup
agent = await MinionCodeAgent.create(
    name="Minion Code Assistant",
    llm="gpt-4o-mini"
)

API Reference