A lightweight, extensible Coding Agent built in Python. Mini Code Agent can autonomously read, edit, and write files, search code, and execute shell commands by leveraging an LLM (Large Language Model) with tool-calling capabilities.
- LLM-Powered Reasoning: Uses OpenAI-compatible APIs to understand user intent and decide which tool to use.
- Tool Calling: Supports a growing set of built-in tools, including file reading, file editing, file writing, code search, and shell execution.
- Agentic Loop: Maintains a multi-turn conversation with the model, automatically passing tool results back until the task is complete.
- Minimal and Clear: A small, readable codebase that is ideal for learning how Coding Agents work under the hood.
mini-code-agent/
|-- main.py # Entry point: interactive REPL loop
|-- requirements.txt # Python dependencies
|-- .env # Environment variables (API key, base URL, model name)
|-- .env_example # Environment variables example file
|-- agent/
| |-- __init__.py
| |-- core.py # Agent core: system prompt, tool-call loop, message management
|-- llm/
| |-- __init__.py
| |-- client.py # LLM client: wraps the OpenAI-compatible chat API
|-- tools/
| |-- __init__.py
| |-- registry.py # Tool registry: maps tool names to functions and defines tool schemas
| |-- file.py # read_file tool
| |-- edit.py # edit_file tool
| |-- write.py # write_file tool
| |-- search.py # search_code tool
| |-- shell.py # run_shell tool
- The user enters a prompt in the terminal.
- The Agent builds a message list containing a system prompt and the user input, then sends it to the LLM.
- If the LLM decides a tool is needed, the Agent executes the corresponding tool (read, edit, write, search, or shell) and appends the result back into the conversation.
- The Agent loops until the LLM produces a final answer without any further tool calls.
- The final response is printed to the terminal.
- Python 3.10+
- An OpenAI-compatible API key and endpoint (e.g., Volcengine Ark, OpenAI, or other compatible services)
- Clone the repository:
git clone https://github.com/Case3y/mini-code-agent
cd mini-code-agent- Install dependencies:
pip install -r requirements.txt- Configure environment variables. Create a
.envfile in the project root:
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://your-api-endpoint/v1
MODEL=your-model-nameRun the agent:
python main.pyYou will see an interactive prompt. Type your request and press Enter. Type exit or quit to leave.
Mini Code Agent
> Who are you?
Mini Code:
I'm Mini Code Agent, a coding assistant that can help you with software development tasks. I have access to tools that let me:
- Read files from your filesystem
- Edit existing files by replacing code snippets
- Write new files to your filesystem
- Search code across your codebase
- Run shell commands to execute programs, install packages, run tests, etc.
Whether you need help writing code, debugging, exploring a codebase, or automating tasks, I'm here to help! Just let me know what you'd like to work
on. 😊
| Tool | Description |
|---|---|
| read_file | Read the text content of a given file path |
| edit_file | Modify an existing file by replacing a text snippet |
| write_file | Write content to a new or existing file |
| search_code | Search for a keyword across the project |
| run_shell | Execute a shell command and return output |
Adding a new tool is simple:
- Implement the tool function in the
tools/directory. - Register it in
tools/registry.pyby adding it to theTOOLSdict and defining its schema inTOOLS_SCHEMA.
Example:
# tools/example.py
def my_tool(param: str):
return f"Result for {param}"# tools/registry.py
from tools.example import my_tool
TOOLS = {
...
"my_tool": my_tool,
}
TOOLS_SCHEMA = [
...
{
"type": "function",
"function": {
"name": "my_tool",
"description": "Describe what it does",
"parameters": {
"type": "object",
"properties": {
"param": {"type": "string"}
},
"required": ["param"]
}
}
},
]- openai - LLM API client
- python-dotenv - Environment variable loader
- rich - Terminal formatting
MIT