tangledgroup Mini-Coding-Agent
Overview
Mini-Coding-Agent is a minimal standalone coding agent framework by Sebastian Raschka. It runs entirely locally through Ollama with zero Python runtime dependencies beyond the standard library. The agent operates in an interactive REPL loop, accepting natural language tasks and executing them through structured tools — file reads, writes, patches, shell commands, and search — with approval gates for risky operations.
The entire codebase is a single mini_coding_agent.py file (~600 lines) organized around six core architectural components: live repo context, prompt shape with cache reuse, structured tools with validation and permissions, context reduction and output management, transcripts with memory and resumption, and bounded subagent delegation.
When to Use
- Building or studying a minimal coding agent architecture from scratch
- Operating a local AI coding assistant backed by Ollama (no cloud API keys needed)
- Understanding how coding agents manage workspace context, tool use, memory, and session persistence
- Creating test-driven development workflows with autonomous code generation
- Learning the patterns behind agent harnesses: prompt construction, tool parsing, approval gates, and context management
- Extending or adapting the six-component agent architecture for custom use cases
Core Concepts
Six Component Architecture
The agent is organized around six practical building blocks:
Live Repo Context — The agent collects stable workspace facts upfront: repo layout, git state, branch info, recent commits, and key documentation files. This context is injected into every prompt so the model always knows what it is working with.
Prompt Shape and Cache Reuse — A stable prompt prefix (rules, tools, workspace context) is separated from the changing transcript and user request. This allows Ollama's prompt caching to reuse static parts efficiently across turns.
Structured Tools, Validation, and Permissions — The model works through named tools with checked inputs, workspace path validation, and approval gates. No free-form arbitrary actions — every tool call is validated before execution.
Context Reduction and Output Management — Long outputs are clipped, repeated reads are deduplicated, and older transcript entries are compressed to keep prompt size under control. Write operations clear read deduplication so the model sees updated content.
Transcripts, Memory, and Resumption — The runtime keeps both a full durable transcript (saved as JSON) and a smaller working memory (task, tracked files, notes). Sessions can be resumed while preserving important state.
Delegation and Bounded Subagents — Scoped subtasks can be delegated to read-only child agents that inherit enough context to help but operate within strict limits (max depth, read-only mode, no risky tools).
Tool Protocol
The agent expects the model to emit one of two response types:
- Tool call —
<tool>{"name":"tool_name","args":{...}}</tool>for JSON-style, or XML-style<tool name="write_file" path="file.py"><content>...</content></tool>for multi-line content - Final answer —
<final>your answer</final>
The parser handles both formats and provides retry notices when the model returns malformed output.
Approval Policy
Risky tools (run_shell, write_file, patch_file) are gated by approval:
ask— prompts the user before risky actions (default, recommended)auto— allows risky actions automatically (use only with trusted prompts and repos)never— denies all risky actions
Session Persistence
Sessions are saved as JSON files under .mini-coding-agent/sessions/ in the workspace root. Each session contains:
id— timestamped unique identifiercreated_at— ISO timestampworkspace_root— absolute path to the repo roothistory— full transcript of user messages, tool calls, and model responsesmemory— distilled working memory with task, tracked files, and notes
Installation / Setup
Prerequisites
- Python 3.10+
- Ollama installed and running (
ollama serve) - An Ollama model pulled locally (default:
qwen3.5:4b)
Quick Start
git clone https://github.com/rasbt/mini-coding-agent.git
cd mini-coding-agent
python mini_coding_agent.py
Or with uv for the CLI entry point:
uv run mini-coding-agent
Key CLI Flags
--cwd <path>— workspace directory (default:.)--model <name>— Ollama model name (default:qwen3.5:4b)--host <url>— Ollama server URL (default:http://127.0.0.1:11434)--approval <mode>— approval policy:ask,auto, ornever(default:ask)--max-steps <n>— max tool/model iterations per request (default:6)--max-new-tokens <n>— max model output tokens per step (default:512)--temperature <f>— sampling temperature (default:0.2)--resume <id|latest>— resume a saved session
Interactive Commands
Inside the REPL:
/help— list available slash commands/memory— print distilled working memory/session— print path to current session JSON/reset— clear session history and memory/exitor/quit— exit the agent
Usage Examples
One-shot prompt
python mini_coding_agent.py --cwd ./my-project "Create a hello.py that prints hello world"
Interactive session with auto-approval
uv run mini-coding-agent --cwd ./my-project --approval auto
Resume the latest session
uv run mini-coding-agent --resume latest
Point at a custom Ollama host and model
python mini_coding_agent.py \
--host http://remote-server:11434 \
--model "qwen3.5:9b" \
--max-steps 10
Advanced Topics
Six Components Deep Dive: Architecture breakdown of workspace context, prompt shape, tools, context reduction, memory, and delegation → Six Components
Tool Reference: Complete reference for all seven built-in tools with schemas, validation rules, and examples → Tool Reference
Session and Memory System: Transcript persistence, working memory distillation, session resumption, and the FakeModelClient testing pattern → Session and Memory