mini-coding-agent is a small standalone coding agent project. Its core file is mini_coding_agent.py, and it provides the CLI command mini-coding-agent. Its goal is not to pursue robustness, but to explain the core components of a coding agent through highly readable code, so the overall design is deliberately kept minimal.
The main capabilities are organized around six practical building blocks:
- Real-time repository context: the agent collects stable workspace facts in advance, such as repository layout, instructions, and git status.
- Prompt shape and cache reuse: the stable prompt prefix is separated from the changing request, transcript, and memory, so repeated model calls can efficiently reuse the static portion.
- Structured tools, validation, and permissions: the model works through named tools, inputs are checked, workspace paths are validated, and approval gating is applied, rather than allowing arbitrary free-form operations.
- Context reduction and output management: long outputs are truncated, repeated reads are deduplicated, and earlier transcript entries are compacted to keep the prompt size within a reasonable range.
- Transcript, memory, and recovery: the runtime keeps a complete persistent transcript and a smaller working memory, so sessions can be resumed while preserving important state.
- Delegation and bounded subagents: clearly scoped subtasks can be delegated to helper agents, which inherit enough context to be helpful, but their operations stay within limits.
Usage: Ollama must be installed first, and an Ollama model must be pulled locally. Using uv for environment management and the CLI entry point is recommended, but the project has no Python runtime dependencies beyond the standard library, so it can also be run directly with python mini_coding_agent.py. The default model is qwen3.5:4b. If there is enough memory, you can try qwen3.5:9b or other larger Qwen 3.5 variants. The agent simply sends prompts to Ollama's /api/generate endpoint.
After startup, the default model is qwen3.5:4b. Risky tools (such as shell commands and file writes) are approval-gated by default and can be controlled with the --approval option: ask (default, prompt before risky operations), auto (automatically allow risky operations, including arbitrary command execution and file writes; should only be used with trusted prompts and trusted repositories), never (reject risky operations).
Sessions are saved under the root directory of the target workspace, and the latest session can be resumed with --resume latest, or a specified session can be resumed with --resume <id>. The interactive REPL supports slash commands: /help shows the list of available commands, /memory prints the distilled session memory (including the current task, tracked files, and notes), /session prints the path to the currently saved session JSON file, /reset clears the current session history and distilled memory but stays in the REPL, /exit exits the interactive session, and /quit exits and is an alias for /exit.
Important CLI flags include: --cwd sets the workspace directory (default .), --model selects the Ollama model name (default qwen3.5:4b), --host specifies the Ollama server URL (default http://127.0.0.1:11434），--ollama-timeout controls how long the client waits for an Ollama response (default 300 seconds), --resume resumes a saved session, --approval controls how risky tools are handled, --max-steps limits the number of model and tool turns allowed for a single user request (default 6), --max-new-tokens limits the model output length per step (default 512), --temperature controls sampling randomness (default 0.2), and --top-p controls nucleus sampling (default 0.9).
The agent expects the model to output <tool>...</tool> or <final>...</final>. Different Ollama models vary in how reliably they follow these instructions; if a model does not follow the format well, a model with stronger instruction-following ability should be used. The project is intentionally kept small and optimized for readability rather than robustness. The detailed tutorial is Components of a Coding Agent.
