{"id":14981553,"url":"https://github.com/builderio/micro-agent","last_synced_at":"2025-05-13T15:10:47.968Z","repository":{"id":242298581,"uuid":"804867341","full_name":"BuilderIO/micro-agent","owner":"BuilderIO","description":"An AI agent that writes (actually useful) code for you","archived":false,"fork":false,"pushed_at":"2024-11-14T17:27:03.000Z","size":6312,"stargazers_count":3974,"open_issues_count":38,"forks_count":344,"subscribers_count":39,"default_branch":"main","last_synced_at":"2025-04-23T18:56:24.451Z","etag":null,"topics":["agent","ai","figma","javascript","react","typescript"],"latest_commit_sha":null,"homepage":"https://www.builder.io/blog/micro-agent","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BuilderIO.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2024-05-23T12:30:24.000Z","updated_at":"2025-04-23T15:01:50.000Z","dependencies_parsed_at":"2024-08-28T17:40:10.863Z","dependency_job_id":"9b5c71f5-b2fc-42ae-96af-d40afefeb51a","html_url":"https://github.com/BuilderIO/micro-agent","commit_stats":{"total_commits":287,"total_committers":13,"mean_commits":"22.076923076923077","dds":0.2195121951219512,"last_synced_commit":"84fdab6d464c916417e245c88d8c951fc321314d"},"previous_names":["builderio/micro-agent"],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BuilderIO%2Fmicro-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BuilderIO%2Fmicro-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BuilderIO%2Fmicro-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BuilderIO%2Fmicro-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BuilderIO","download_url":"https://codeload.github.com/BuilderIO/micro-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253969248,"owners_count":21992263,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["agent","ai","figma","javascript","react","typescript"],"created_at":"2024-09-24T14:03:48.491Z","updated_at":"2025-05-13T15:10:42.945Z","avatar_url":"https://github.com/BuilderIO.png","language":"TypeScript","readme":"\u003cbr\u003e\n\u003cdiv align=\"center\"\u003e\n   \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F4d36bc052c4340f997dd61eb19c1c64b\"\u003e\n      \u003cimg width=\"400\" alt=\"AI Shell logo\" src=\"https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F1a718d297d644fce90f33e93b7e4061f\"\u003e\n    \u003c/picture\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n   An AI agent that writes and fixes code for you.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003ca href=\"https://www.npmjs.com/package/@builder.io/micro-agent\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@builder.io/micro-agent\" alt=\"Current version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\n![Demo](https://cdn.builder.io/api/v1/file/assets%2FYJIGb4i01jvw0SRdL5Bt%2F3306a1cff57b4be69df65492a72ae8e5)\n\n# Micro Agent\n\nJust run `micro-agent`, give it a prompt, and it'll generate a test and then iterate on code until all test cases pass.\n\n## Why?\n\nLLMs are great at giving you broken code, and it can take repeat iteration to get that code to work as expected.\n\nSo why do this manually when AI can handle not just the generation but also the iteration and fixing?\n\n### Why a \"micro\" agent?\n\nAI agents are cool, but general-purpose coding agents rarely work as hoped or promised. They tend to go haywire with compounding errors. Think of your Roomba getting stuck under a table, x1000.\n\nThe idea of a micro agent is to\n\n1. Create a definitive test case that can give clear feedback if the code works as intended or not, and\n2. Iterate on code until all test cases pass\n\nRead more on [why Micro Agent exists](https://www.builder.io/blog/micro-agent).\n\n\u003cimg width=\"1270\" alt=\"Micro Agent Diagram\" src=\"https://github.com/BuilderIO/micro-agent/assets/844291/406496dd-3be8-491b-a5f0-2960dd924013\"\u003e\n\n### What this project is not\n\nThis project is not trying to be an end-to-end developer. AI agents are not capable enough to reliably try to be that yet (or probably very soon). This project won't install modules, read and write multiple files, or do anything else that is highly likely to cause havoc when it inevitably fails.\n\nIt's a micro agent. It's small, focused, and does one thing as well as possible: write a test, then produce code that passes that test.\n\n## Installation\n\n\u003e Micro Agent requires [Node.js](https://nodejs.org/) v18 or later.\n\n```bash\nnpm install -g @builder.io/micro-agent\n```\n\n## Getting Started\n\nThe best way to get started is to run Micro Agent in interactive mode, where it will ask you questions about the code it generates and use your feedback to improve the code it generates.\n\n```bash\nmicro-agent\n```\n\nLook at that, you're now a test-driven developer. You're welcome.\n\n## Running Manually\n\n### Add an LLM API key\n\nMicro Agent works with Claude, OpenAI, Ollama, or any OpenAI compatible provider such as Groq. You need to add your API key to the CLI:\n\n```bash\nmicro-agent config set OPENAI_KEY=\u003cyour token\u003e\nmicro-agent config set MODEL=gpt-4o\n```\n\nOr, for Claude:\n\n```bash\nmicro-agent config set ANTHROPIC_KEY=\u003cyour token\u003e\nmicro-agent config set MODEL=claude\n```\n\nTo use a custom OpenAI API endpoint, such as for use with Ollama or Groq, you can set the endpoint with:\n\n```bash\nmicro-agent config set OPENAI_API_ENDPOINT=\u003cyour endpoint\u003e\nmicro-agent config set OPENAI_API_ENDPOINT=https://api.groq.com/openai/v1\n```\n\n### Unit test matching\n\n![Demo](https://cdn.builder.io/api/v1/file/assets%2FYJIGb4i01jvw0SRdL5Bt%2F4e8b02abb3e044118f070d9a7253003e)\n\nTo run the Micro Agent on a file in unit test matching mode, you need to provide a test script that will run after each code generation attempt. For instance:\n\n```bash\nmicro-agent ./file-to-edit.ts -t \"npm test\"\n```\n\nThis will run the Micro Agent on the file `./file-to-edit.ts` running `npm test` and will write code until the tests pass.\n\nThe above assumes the following file structure:\n\n```bash\nsome-folder\n├──file-to-edit.ts\n├──file-to-edit.test.ts # test file. if you need a different path, use the -f argument\n└──file-to-edit.prompt.md # optional prompt file. if you need a different path, use the -p argument\n```\n\nBy default, Micro Agent assumes you have a test file with the same name as the editing file but with `.test.ts` appended, such as `./file-to-edit.test.ts` for the above examples.\n\nIf this is not the case, you can specify the test file with the `-f` flag. You can also add a prompt to help guide the code generation, either at a file located at `\u003cfilename\u003e.prompt.md` like `./file-to-edit.prompt.md` or by specifying the prompt file with the `-p`. For instance:\n\n```bash\nmicro-agent ./file-to-edit.ts -t \"npm test\" -f ./file-to-edit.spec.ts -p ./path-to-prompt.prompt.md\n```\n\n### Visual matching (experimental)\n\n![Visual Demo](https://cdn.builder.io/api/v1/file/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fe90f6d4158b44a8fb9adeee3be3dbe82)\n\n\u003e [!WARNING]\n\u003e This feature is experimental and under active development. Use with caution.\n\nMicro Agent can also help you match a design. To do this, you need to provide a design and a local URL to your rendered code. For instance:\n\n```bash\nmicro-agent ./app/about/page.tsx --visual localhost:3000/about\n```\n\nMicro agent will then generate code until the rendered output of your code more closely matches a screenshot file that you place next to the code you are editing (in this case, it would be `./app/about/page.png`).\n\nThe above assumes the following file structure:\n\n```bash\napp/about\n├──page.tsx # The code to edit\n├──page.png # The screenshot to match\n└──page.prompt.md # Optional, additional instructions for the AI\n```\n\n### Adding an Anthropic API key\n\n\u003e [!NOTE]\n\u003e Using the visual matching feature requires an Anthropic API key.\n\nOpenAI is simply just not good at visual matching. We recommend using [Anthropic](https://anthropic.com/) for visual matching. To use Anthropic, you need to add your API key to the CLI:\n\n```bash\nmicro-agent config set ANTHROPIC_KEY=\u003cyour token\u003e\n```\n\nVisual matching uses a multi-agent approach where Anthropic Claude Opus will do the visual matching and feedback, and then OpenAI will generate the code to match the design and address the feedback.\n\n![Visual of the multi agent approach](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F427929ba84b34ac6a0f1fda104e60ecd)\n\n### Integration with Figma\n\nMicro Agent can also integrate with [Visual Copilot](https://www.builder.io/c/docs/visual-copilot) to connect directly with Figma to ensure the highest fidelity possible design to code, including fully reusing the exact components and design tokens from your codebase.\n\nVisual Copilot connects directly to Figma to assist with pixel perfect conversion, exact design token mapping, and precise reusage of your components in the generated output.\n\nThen, Micro Agent can take the output of Visual Copilot and make final adjustments to the code to ensure it passes TSC, lint, tests, and fully matches your design including final tweaks.\n\n![Visual Copilot demo](https://cdn.builder.io/api/v1/file/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa503ad8367d746f3879db1a155728cb2)\n\n## Configuration\n\n### Max runs\n\nBy default, Micro Agent will do 10 runs. If tests don't pass in 10 runs, it will stop. You can change this with the `-m` flag, like `micro-agent ./file-to-edit.ts -m 20`.\n\n### Config\n\nYou can configure the CLI with the `config` command, for instance to set your OpenAI API key:\n\n```bash\nmicro-agent config set OPENAI_KEY=\u003cyour token\u003e\n```\n\nor to set an Anthropic key:\n\n```bash\nmicro-agent config set ANTHROPIC_KEY=\u003cyour token\u003e\n```\n\nBy default Micro Agent uses `gpt-4o` as the model, but you can override it with the `MODEL` config option (or environment variable):\n\n```bash\nmicro-agent config set MODEL=gpt-3.5-turbo\n```\n\nor, if you supply an Anthropic key, you can use any Claude model. by default `claude` is an alias to `claude-3-5-sonnet-20241022`:\n\n```bash\nmicro-agent config set MODEL=claude\n```\n\n#### Config UI\n\nTo use a more visual interface to view and set config options you can type:\n\n```bash\nmicro-agent config\n```\n\nTo get an interactive UI like below:\n\n```bash\n◆  Set config:\n│  ○ OpenAI Key\n│  ○ Anthropic Key\n│  ○ OpenAI API Endpoint\n│  ● Model (gpt-4o)\n│  ○ Done\n└\n```\n\n#### Environment variables\n\nAll config options can be overridden as environment variables, for instance:\n\n```bash\nMODEL=gpt-3.5-turbo micro-agent ./file-to-edit.ts -t \"npm test\"\n```\n\n### Upgrading\n\nCheck the installed version with:\n\n```bash\nmicro-agent --version\n```\n\nIf it's not the [latest version](https://github.com/BuilderIO/micro-agent/tags), run:\n\n```bash\nmicro-agent update\n```\n\nOr manually update with:\n\n```bash\nnpm update -g @builder.io/micro-agent\n```\n\n## Contributing\n\nWe would love your contributions to make this project better, and gladly accept PRs. Please see [./CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute.\n\nIf you are looking for a good first issue, check out the [good first issue](https://github.com/BuilderIO/micro-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label.\n\n## Feedback\n\nIf you have any feedback, please open an issue or @ me at [@steve8708](https://twitter.com/steve8708) on Twitter.\n\n## Usage\n\n```bash\nUsage:\n  micro-agent \u003cfile path\u003e [flags...]\n  micro-agent \u003ccommand\u003e\n\nCommands:\n  config        Configure the CLI\n  update        Update Micro Agent to the latest version\n\nFlags:\n  -h, --help                      Show help\n  -m, --max-runs \u003cnumber\u003e         The maximum number of runs to attempt\n  -p, --prompt \u003cstring\u003e           Prompt to run\n  -t, --test \u003cstring\u003e             The test script to run\n  -f, --test-file \u003cstring\u003e        The test file to run\n  -v, --visual \u003cstring\u003e           Visual matching URL\n      --thread \u003cstring\u003e           Thread ID to resume\n      --version                   Show version\n```\n\n\u003cbr\u003e\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003ca href=\"https://www.builder.io/m/developers\"\u003e\n      \u003cpicture\u003e\n         \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://user-images.githubusercontent.com/844291/230786554-eb225eeb-2f6b-4286-b8c2-535b1131744a.png\"\u003e\n         \u003cimg width=\"250\" alt=\"Made with love by Builder.io\" src=\"https://user-images.githubusercontent.com/844291/230786555-a58479e4-75f3-4222-a6eb-74c5af953eac.png\"\u003e\n       \u003c/picture\u003e\n   \u003c/a\u003e\n\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuilderio%2Fmicro-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuilderio%2Fmicro-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuilderio%2Fmicro-agent/lists"}