A minimal, readable Python implementation of a coding agent harness, this project demystifies the core components of autonomous coding agents. It targets engineers and researchers seeking to understand or build upon agent architectures, providing a practical, modular framework with features for context management, structured tool use, and session persistence.

How It Works

The agent employs a loop built around six key components: collecting stable workspace context (repo layout, instructions, git state), utilizing a prompt cache for efficiency, enforcing structured tools with validation and approval gates, managing context via output clipping and transcript compression, persisting sessions through durable transcripts and working memory, and enabling bounded delegation to subagents. This design prioritizes clarity and educational value, with Ollama serving as the current model backend.

Quick Start & Requirements

• Requirements: Python 3.10+, Ollama installed and running with a local model pulled (default: qwen3.5:4b).
• Installation: Clone the repository. Environment management via uv is optional.
• Usage: Start with uv run mini-coding-agent or python mini_coding_agent.py.
• Ollama Setup: Install from https://ollama.com/download, run ollama serve, and pull a model (e.g., ollama pull qwen3.5:4b).
• Docs: Ollama download: https://ollama.com/download, Model library: https://ollama.com/library/qwen3.5.

Highlighted Details

• Modular Architecture: Built around six practical blocks: Live repo context, Prompt caching, Structured tools, Context reduction, Session persistence, and Bounded delegation.
• Approval Gating: Risky operations (shell commands, file writes) are protected by --approval ask (default), --approval auto, or --approval never modes.
• Session Resumption: Supports resuming sessions via --resume latest or --resume <session_id>, saving state in .mini-coding-agent/sessions/.
• Interactive REPL: Includes commands like /help, /memory, /session, /reset, and /exit for in-session control.

Maintenance & Community

No specific details regarding maintainers, community channels (e.g., Discord/Slack), or roadmap were found in the provided README snippet.

Licensing & Compatibility

The license type and any compatibility notes for commercial use or closed-source linking are not explicitly stated in the provided README.

Limitations & Caveats

The project prioritizes readability and educational clarity over robustness. Model output reliability, particularly regarding structured tool/final tag emission, is dependent on the chosen Ollama model's instruction-following capabilities. The absence of a stated license poses a potential adoption blocker.