Content
# MiniAgent
🚀 **Create Your Own AI Coding Assistant and Command-Line Tool in Just 5 Minutes!** | [English](README_EN.md)
<div align="center">
<img src="resource/miniagent.png" alt="MiniAgent" width="400"/>
[](LICENSE)
[](https://python.org)
[](https://github.com/ZhuLinsen/MiniAgent)
</div>
## 💡 Core Features
**A single `agent.py` file replicates Claude Code's programming capabilities and Manus's system control abilities!**
MiniAgent is a **minimalist, transparent, and powerful CLI Agent framework**, rejecting cumbersome dependencies and complex architectures:
- 🧠 **Code Agent**: Write code, fix bugs, and run tests like Claude Code
- 🦾 **OS Agent**: Control browsers, edit documents, and manage applications like Manus
- ⚡ **Minimalist Implementation**: The core engine `agent.py` is fully transparent and controllable, suitable for learning and modification
- 🤖 **Full Model Support**: Compatible with all models that support the OpenAI interface, including DeepSeek, OpenAI, and Claude
- 🔌 **High Extensibility**: Minimalist decorator pattern, adding custom tools in just 3 lines of code
- 🔄 **Dual-Mode Tool Calling**: Text parsing mode (transparent and learnable) + Native Function Calling mode (more reliable)
- 🎯 **Skill System**: Reusable Agent configurations, with built-in coder, researcher, reviewer, and tester roles
- 🛡️ **Safety Protection**: Automatic interception and confirmation of dangerous commands to prevent destructive operations caused by LLM hallucinations
- 💬 **Streaming Output**: Real-time output with a typing effect, automatic context compression for long conversations
- 🔗 **MCP Protocol**: Supports connecting to MCP tool servers, accessing the community ecosystem
- 🤝 **Agent Orchestration**: Built-in orchestrator, supporting task decomposition and multi-role collaboration
## 🤔 Why MiniAgent?
| | MiniAgent | smolagents | pydantic-ai | LangChain |
|---|---|---|---|---|
| **Core Positioning** | CLI Agent Textbook | HuggingFace Ecosystem | Enterprise-Level Type Safety | Universal Framework |
| **Core Code** | Single File, Readable | ~1,000 lines | 182MB | 100,000+ lines |
| **Tool Calling** | Text Parsing + Native FC | Code Agent | Native FC | Multi-Layer Abstraction |
| **Learning Curve** | ⭐ 30 minutes to get started | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **Dependencies** | 7 | ~20 | ~15 | 50+ |
| **OS Control** | bash Universal | Requires Extension | Requires Extension | Requires Plugin |
> **MiniAgent's Unique Value: The Best AI Agent Textbook.** No magic, no abstraction, beginners can fully understand how Agents work.
## Design Philosophy
> **MiniAgent does not come with 100 tools, but uses 6 code tools + bash to achieve infinite possibilities.**
- Need a screenshot? LLM will `bash: python -c "from mss import mss; mss().shot()"`
- Need to control the mouse? LLM will `bash: python -c "import pyautogui; pyautogui.click(100,200)"`
- Need to crawl a webpage? LLM will `bash: curl ... | python -c "..."`
This is the power of minimalism: let LLM do what it's best at - **thinking and combining**.
## Quick Start
```bash
git clone https://github.com/ZhuLinsen/MiniAgent.git && cd MiniAgent
pip install -r requirements.txt && pip install -e .
cp .env.example .env # Fill in your API Key
miniagent # Start!
```
<details>
<summary>📋 Detailed Installation Instructions</summary>
### Installation
```bash
git clone https://github.com/ZhuLinsen/MiniAgent.git
cd MiniAgent
pip install -r requirements.txt
pip install -e . # Install miniagent command
```
### Configuration
Create a `.env` file (refer to `.env.example`):
```bash
LLM_API_KEY=your_api_key_here
LLM_MODEL=deepseek-chat
LLM_API_BASE=https://api.deepseek.com/v1
```
### Run
```bash
miniagent # or python -m miniagent
```
</details>
## Example Usage
```
you: Help me create a hello.py file
● write hello.py (1 lines)
→ ok
🤖 Created hello.py file!
you: Run it
● bash python hello.py
→ Hello World!
🤖 Successful execution!
```
## ⚡ Demo
### 1. Browser Search Automation
> Prompt: "Open the browser, then search for 'zhulinsen/miniagent' on Google."
<img src="resource/miniagent_chrome.gif" alt="Browser Automation Demo" width="100%"/>
### 2. Office Automation (Word)
> Prompt: "Write a 500-word overview of AI agents in Word and format"
<img src="resource/miniagent_word.gif" alt="Word Creation Demo" width="100%"/>
### 3. Code Generation (Coding)
> Prompt: "Create a ppo.py implementation and perform testing"
<img src="resource/miniagent_coding.png" alt="Coding Demo" width="100%"/>
## Built-in Tools
| Category | Tool | Description |
|---|---|---|
| **Coding** | `read` | Read file content |
| | `write` | Create/overwrite file |
| | `edit` | Edit file specified line |
| | `grep` | Search file content |
| | `glob` | List matching files |
| | `bash` | Execute Shell command (supports timeout control) |
| **OS** | `open_browser` | Open webpage or search |
| | `open_app` | Launch local application (calc, notepad...) |
| | `create_docx` | Create Word document |
| | `clipboard_copy`| Copy to clipboard |
| | `clipboard_read`| Read clipboard content |
| **System** | `system_info` | System information |
| | `system_load` | CPU/memory/disk load |
| | `process_list` | Process list |
| | `disk_usage` | Disk usage |
| | `env_get` | Read environment variable |
| | `env_set` | Set environment variable |
| **Misc** | `calculator` | Math calculation (AST safe evaluation) |
| | `get_current_time` | Current time |
| | `web_search` | Web search |
| | `http_request` | HTTP request |
| | `file_stats` | File/directory statistics |
## Project Structure
```
miniagent/
├── agent.py # 🧠 Core Agent engine (start reading from here!)
│ # LLM loop + tool calling + context management
├── cli.py # 💬 Interactive command-line interface (Rich + streaming output)
├── tools/ # 🔧 Toolset
│ ├── code_tools.py # Code tools (read/write/edit/grep/glob/bash)
│ └── basic_tools.py # Basic tools (calculator/browser/clipboard/docx...)
├── extensions/ # 🔌 Optional extensions
│ ├── mcp_client.py # MCP protocol client
│ └── orchestrator.py # Multi-Agent orchestrator
├── skills.py # 🎯 Skill system (reusable Agent role configurations)
├── config.py # ⚙️ Configuration management (.env + JSON + environment variables)
├── memory.py # 💾 Lightweight session memory
└── utils/ # Utility functions
├── json_utils.py # Robust JSON parsing
├── text_utils.py # Text processing
└── reflector.py # Reflection mechanism (optional)
```
## Dual-Mode Tool Calling
MiniAgent supports two tool calling modes for easy learning and comparison:
### Text Mode (Default)
LLM outputs structured text in response, Agent parses and executes — **fully transparent, best teaching mode**:
```python
agent.run("Calculate 2+2") # Default text mode
```
### Native Function Calling Mode
Use OpenAI-compatible tools parameter — **more reliable, supports parallel tool calls**:
```python
agent.run("Calculate 2+2", mode="native") # Native FC mode
```
## MCP Protocol Support
Connect to any MCP tool server, access the community ecosystem with one line of code:
```python
from miniagent import MiniAgent, load_mcp_tools
agent = MiniAgent(model="deepseek-chat", api_key="...")
# Load MCP file system tool
for tool in load_mcp_tools("npx @anthropic/mcp-server-filesystem /tmp"):
agent.add_tool(tool)
```
## Agent Orchestration
Built-in orchestrator, automatically decomposes complex tasks and assigns them to professional workers (based on the Skill system):
```python
from miniagent import Orchestrator
orch = Orchestrator(model="deepseek-chat", api_key="...", base_url="...")
result = orch.run("Research Python asynchronous mode, write a demo and test")
# Automatic planning: researcher → coder → tester
```
## Skill System
Skill is a reusable Agent configuration: prompt + tool whitelist + parameters. Four built-in Skills, custom ones also supported:
```python
from miniagent import MiniAgent, Skill, register_skill
# Use built-in Skill
agent = MiniAgent(model="deepseek-chat", api_key="...", base_url="...")
agent.load_all_tools()
agent.load_skill("coder") # Automatically set code expert prompt + only retain code tools
# Custom Skill
register_skill(Skill(
name="devops",
prompt="You are a DevOps engineer. Focus on CI/CD, Docker, and infrastructure.",
tools=["bash", "read", "write"],
temperature=0.3,
))
```
## Custom Tools
```python
from miniagent import MiniAgent
from miniagent.tools import register_tool
@register_tool
def my_tool(arg: str) -> str:
"""My custom tool"""
return f"Processing: {arg}"
agent = MiniAgent(...)
agent.load_builtin_tool("my_tool")
```
## Comparison with Similar Projects
| Feature | MiniAgent | smolagents | pydantic-ai | LangChain |
|------|-----------|-----------|------------|-----------|
| Core Code | Single file, readable | ~1,000 lines | 182MB | 100,000+ lines |
| Tool Calling | Text parsing + Native FC dual modes | Code Agent | Native FC | Multi-layer abstraction |
| Readability | ⭐⭐⭐⭐⭐ Beginner-friendly | ⭐⭐⭐⭐ Compact | ⭐⭐⭐ Enterprise-level | ⭐⭐ Complex |
| OS Control | bash Universal + dedicated tools | Requires extension | Requires extension | Requires plugin |
| Teaching Value | Best Agent textbook | HuggingFace ecosystem strong | Type safety best | Too complex |
| Model Support | Full model compatibility | Full model | Full model | Full model |
| Skill System | ✅ Built-in | ❌ | ❌ | ❌ |
| MCP Support | ✅ | ❌ | ✅ | Requires plugin |
## Acknowledgements
MiniAgent's Code Tools design references the [nanocode](https://github.com/1rgs/nanocode) project, thanks for its elegant minimalist implementation ideas!
## License
[Apache License 2.0](LICENSE)
⭐ If this project helps you, give it a Star!
