{"id":49326847,"url":"https://github.com/rasbt/mini-coding-agent","last_synced_at":"2026-04-26T20:32:31.190Z","repository":{"id":348628291,"uuid":"1199057215","full_name":"rasbt/mini-coding-agent","owner":"rasbt","description":"Minimal and readable coding agent harness implementation in Python to explain the core components of coding agents.","archived":false,"fork":false,"pushed_at":"2026-04-02T03:07:10.000Z","size":22,"stargazers_count":39,"open_issues_count":2,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T15:47:02.764Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rasbt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T02:35:06.000Z","updated_at":"2026-04-02T15:20:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rasbt/mini-coding-agent","commit_stats":null,"previous_names":["rasbt/mini-coding-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rasbt/mini-coding-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rasbt%2Fmini-coding-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rasbt%2Fmini-coding-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rasbt%2Fmini-coding-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rasbt%2Fmini-coding-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rasbt","download_url":"https://codeload.github.com/rasbt/mini-coding-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rasbt%2Fmini-coding-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32312321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T19:15:34.056Z","status":"ssl_error","status_checked_at":"2026-04-26T19:15:15.467Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-26T20:32:29.475Z","updated_at":"2026-04-26T20:32:31.175Z","avatar_url":"https://github.com/rasbt.png","language":"Python","funding_links":[],"categories":["Reference Implementations","Frameworks \u0026 Libraries"],"sub_categories":["Tutorials \u0026 Educational","Code Agents"],"readme":"\u0026nbsp;\n# Mini-Coding-Agent\n\nThis folder contains a small standalone coding agent:\n\n- code: `mini_coding_agent.py`\n- CLI: `mini-coding-agent`\n\nIt is a minimal local agent loop with:\n\n- workspace snapshot collection\n- stable prompt plus turn state\n- structured tools\n- approval handling for risky tools\n- transcript and memory persistence\n- bounded delegation\n\nThe model backend is currently based on Ollama.\n\n\u003ca href=\"https://magazine.sebastianraschka.com/p/components-of-a-coding-agent\"\u003e\n  \u003cimg src=\"https://substack-post-media.s3.amazonaws.com/public/images/49b97718-57f4-4977-99c8-8ad5c4d32af3_1548x862.png\" width=\"500px\"\u003e\n\u003c/a\u003e\n\n\u003cbr\u003e\n\n**[The detailed tutorial: Components of a Coding Agent](https://magazine.sebastianraschka.com/p/components-of-a-coding-agent)**\n\n\n\u0026nbsp;\n## Six Core Components\n\n\u003ca href=\"https://magazine.sebastianraschka.com/p/components-of-a-coding-agent\"\u003e\n  \u003cimg alt=\"Six core components of a coding agent\" src=\"https://sebastianraschka.com/images/github/mini-coding-agent/six-components.webp\" width=\"500px\"\u003e\n\u003c/a\u003e\n\nThis coding harness is organized around six practical building blocks:\n\n1. **Live repo context**  \n   The agent collects stable workspace facts upfront, such as repo layout, instructions, and git state.\n2. **Prompt shape and cache reuse**  \n   A stable prompt prefix, which is separate from the changing request, transcript, and memory so repeated model calls can reuse the static parts efficiently.\n3. **Structured tools, validation, and permissions**  \n   The model works through named tools with checked inputs, workspace path validation, and approval gates instead of free-form arbitrary actions.\n4. **Context reduction and output management**  \n   Long outputs are clipped, repeated reads are deduplicated, and older transcript entries are compressed to keep prompt size under control.\n5. **Transcripts, memory, and resumption**  \n   The runtime keeps both a full durable transcript and a smaller working memory so sessions can be resumed while preserving important state via working memory.\n6. **Delegation and bounded subagents**  \n   Scoped subtasks can be delegated to helper agents that inherit enough context to help (but operate within limits).\n\n\u0026nbsp;\n## Requirements\n\nYou need:\n\n- Python 3.10+\n- Ollama installed\n- an Ollama model pulled locally\n\nOptional:\n\n- `uv` for environment management and the `mini-coding-agent` CLI entry point\n\nThis project has no Python runtime dependency beyond the standard library, so you can run it directly with `python mini_coding_agent.py` if you do not want to use `uv`.\n\n\u0026nbsp;\n## Install Ollama\n\nInstall Ollama on your machine so the `ollama` command is available in your shell.\n\nOfficial installation link: [ollama.com/download](https://ollama.com/download)\n\nThen verify:\n\n```bash\nollama --help\n```\n\nStart the server:\n\n```bash\nollama serve\n```\n\nIn another terminal, pull a model. Example:\n\n```bash\nollama pull qwen3.5:4b\n```\n\nQwen 3.5 model library:\n\n- [ollama.com/library/qwen3.5](https://ollama.com/library/qwen3.5)\n\nThe default in this project is `qwen3.5:4b`. If you have sufficient memory, it is worth trying a larger model such as `qwen3.5:9b` or another larger Qwen 3.5 variant. The agent just sends prompts to Ollama's `/api/generate` endpoint.\n\n\u0026nbsp;\n## Project Setup\n\nClone the repo or your fork and change into it:\n\n```bash\ngit clone https://github.com/rasbt/mini-coding-agent.git\ncd mini-coding-agent\n```\n\nIf you forked it first, use your fork URL instead:\n\n```bash\ngit clone https://github.com/\u003cyour-github-user\u003e/mini-coding-agent.git\ncd mini-coding-agent\n```\n\n\n\n\u0026nbsp;\n## Basic Usage\n\nStart the agent:\n\n```bash\ncd mini-coding-agent\nuv run mini-coding-agent\n```\n\nWithout `uv`, run the script directly:\n\n```bash\ncd mini-coding-agent\npython mini_coding_agent.py\n```\n\nBy default it uses:\n\n- model: `qwen3.5:4b`\n- approval: `ask`\n\nFor a concrete usage example, see [EXAMPLE.md](EXAMPLE.md).\n\n\u0026nbsp;\n## Approval Modes\n\nRisky tools such as shell commands and file writes are gated by approval.\n\n- `--approval ask`\n  prompts before risky actions (default and recommended)\n- `--approval auto`\n  allows risky actions automatically, including arbitrary command execution and file writes by the model; use only with trusted prompts and trusted repositories\n- `--approval never`\n  denies risky actions\n\nExample:\n\n```bash\nuv run mini-coding-agent --approval auto\n```\n\n\n\n\u0026nbsp;\n## Resume Sessions\n\nThe agent saves sessions under the target workspace root in:\n\n```text\n.mini-coding-agent/sessions/\n```\n\nResume the latest session:\n\n```bash\nuv run mini-coding-agent --resume latest\n```\n\n\nResume a specific session:\n\n```bash\nuv run mini-coding-agent --resume 20260401-144025-2dd0aa\n```\n\n\n\u0026nbsp;\n## Interactive Commands\n\nInside the REPL, slash commands are handled directly by the agent instead of\nbeing sent to the model as a normal task.\n\n- `/help`\n  shows the list of available interactive commands\n- `/memory`\n  prints the distilled session memory, including the current task, tracked files, and notes\n- `/session`\n  prints the path to the current saved session JSON file\n- `/reset`\n  clears the current session history and distilled memory but keeps you in the REPL\n- `/exit`\n  exits the interactive session\n- `/quit`\n  exits the interactive session; alias for `/exit`\n\n\u0026nbsp;\n## Main CLI Flags\n\n```bash\nuv run mini-coding-agent --help\n```\n\nWithout `uv`:\n\n```bash\npython mini_coding_agent.py --help\n```\n\nCLI flags are passed before the agent starts. Use them to choose the workspace,\nmodel connection, resume behavior, approval mode, and generation limits.\n\nImportant flags:\n\n- `--cwd`\n  sets the workspace directory the agent should inspect and modify; default: `.`\n- `--model`\n  selects the Ollama model name, such as `qwen3.5:4b`; default: `qwen3.5:4b`\n- `--host`\n  points the agent at the Ollama server URL (usually not needed); default: `http://127.0.0.1:11434`\n- `--ollama-timeout`\n  controls how long the client waits for an Ollama response (usually not needed); default: `300` seconds\n- `--resume`\n  resumes a saved session by id or uses `latest`; default: start a new session\n- `--approval`\n  controls how risky tools are handled: `ask`, `auto`, or `never`; default: `ask`\n- `--max-steps`\n  limits how many model and tool turns are allowed for one user request; default: `6`\n- `--max-new-tokens`\n  caps the model output length for each step; default: `512`\n- `--temperature`\n  controls sampling randomness; default: `0.2`\n- `--top-p`\n  controls nucleus sampling for generation; default: `0.9`\n\n\u0026nbsp;\n## Example\n\nSee [EXAMPLE.md](EXAMPLE.md)\n\n\u0026nbsp;\n## Notes \u0026 Tips\n\n- The agent expects the model to emit either `\u003ctool\u003e...\u003c/tool\u003e` or `\u003cfinal\u003e...\u003c/final\u003e`.\n- Different Ollama models will follow those instructions with different reliability.\n- If the model does not follow the format well, use a stronger instruction-following model.\n- The agent is intentionally small and optimized for readability, not robustness.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frasbt%2Fmini-coding-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frasbt%2Fmini-coding-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frasbt%2Fmini-coding-agent/lists"}