{"id":25315694,"url":"https://github.com/kgindle/monkey","last_synced_at":"2026-05-09T00:08:59.832Z","repository":{"id":277273882,"uuid":"931278649","full_name":"kgindle/monkey","owner":"kgindle","description":"A coding monkey.","archived":false,"fork":false,"pushed_at":"2025-02-16T10:20:36.000Z","size":40,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-07T15:53:03.885Z","etag":null,"topics":["ai","chromadb","ollama","python","sqlite"],"latest_commit_sha":null,"homepage":"","language":"Python","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/kgindle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2025-02-12T02:22:31.000Z","updated_at":"2025-02-16T10:20:39.000Z","dependencies_parsed_at":"2025-02-13T04:36:14.331Z","dependency_job_id":null,"html_url":"https://github.com/kgindle/monkey","commit_stats":null,"previous_names":["kgindle/monkey"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kgindle/monkey","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgindle%2Fmonkey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgindle%2Fmonkey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgindle%2Fmonkey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgindle%2Fmonkey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kgindle","download_url":"https://codeload.github.com/kgindle/monkey/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kgindle%2Fmonkey/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32802563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["ai","chromadb","ollama","python","sqlite"],"created_at":"2025-02-13T18:24:44.972Z","updated_at":"2026-05-09T00:08:59.819Z","avatar_url":"https://github.com/kgindle.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Monkey\n\n![GitHub commit activity](https://img.shields.io/github/commit-activity/m/kgindle/monkey)\n[![Discord](https://img.shields.io/discord/1339096899952574547)](https://discord.gg/AYzqUCrx)\n\n![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)\n![Ollama](https://img.shields.io/badge/ollama-81008d?style=for-the-badge\u0026logo=ollama\u0026logoColor=fff)\n![SQLite](https://img.shields.io/badge/sqlite-%2307405e.svg?style=for-the-badge\u0026logo=sqlite\u0026logoColor=white)\n![ChromaDB](https://img.shields.io/badge/chromadb-4A148C.svg?style=for-the-badge\u0026logo=chromadb\u0026logoColor=white)\n\nMonkey 🐒 is a tool for creating autonomous agents that can read and write code\nin your project. The name is inspired by the [Infinite Monkey Theorem]:\n\n\u003e If I let my fingers wander idly over the keys of a typewriter it might happen\n\u003e that my screed made an intelligible sentence. If an army of monkeys were\n\u003e strumming on typewriters they might write all the books in the British Museum.\n\u003e The chance of their doing so is decidedly more favorable than the chance of\n\u003e the molecules returning to one half of the vessel.\n\u003e \n\u003e ---\n\u003e \u003ccite\u003eArthur Eddington (1927)\u003c/cite\u003e\n\nMonkey is built with:\n\n- [Ollama] - Evaluate LLM models like `codegemma-9b` or `llama3-8b`.\n- [ChromaDB] - Vector database for embeddings.\n- [Python] - Smartest snake ever now working with monkeys 😲.\n- [SQLite] - World's most widely deployed database engine.\n\n## How it works\n\nMonkey uses a combination of LLMs and vector embeddings to read code, discuss\ntheir understanding, and write code:\n\n- **See:** Read code and understand it.\n- **Hear:** Listen to feedback from you and other monkeys.\n- **Do:** Write code based on the feedback and their understanding.\n\nMonkey can use multiple autonomous agents (called *monkeys*) that each may\nspecialize in languages, codebases, use different models, have different\nprompts, and more.\n\n## Installation\n\nTo install Monkey:\n\n```bash\ngit clone git@github.com:kgindle/monkey.git\ncd monkey/\npip install -e .\n```\n\nYou will now have the `monkey` command available. You can run `git pull` to\nupdate to the latest version and the Python package will be updated\nautomatically.\n\nUpon first run `monkey` will help you setup your system.\n\n## Usage\n\nTo start using `monkey`, you need to create a [Monkeyfile] in the root of your\nproject. This file describes your project and how the monkeys will code,\nalthough most fields are optional:\n\n```yaml\nname: hello-world\nmodel: llama3-8b\ntest: monkeybars\n```\n\nNow you can run Monkey from within your project directory or any subdirectory.\n\n\n### Monkeys Read Code\n\nYou can instruct Monkey to read and understand code using the `see` command:\n\n```bash\nmonkey see\n```\n\nRunning the `see` command tells Monkey that now is a safe time to read the code\nin your project. This is done by taking a copy of your code and processing it\nlocally in the background. This means it's safe to go back to work while the\nmonkeys are reading the code.\n\nThe `see` command is safe to run multiple times as the content is cached, but\nstress is put on the vector database and LLM resources.\n\nYou can also give specific paths to read:\n    \n```bash\nmonkey see src/main.py\n```\n\nThis is described more in the [Command Options](#command-options) section.\n\n### Listen to feedback\n\nYou can instruct the monkeys to listen to feedback using the `hear` command:\n\n```\n$ monkey hear\n\u003e Use the logging module instead of print statements.\n```\n\nThis can be any feedback you want to provide to the monkeys. The monkeys will\nuse this feedback to improve their code writing and [Monkeymap](#monkeymap).\n\n### Write code\n\nYou can instruct the monkeys to write code using the `do` command:\n\n```bash\nmonkey do\n```\n\nRunning the `do` command tells Monkey that now is a safe time to write code in\nyour project based on the code they have read and the feedback they have\nreceived. If you have modified the code since, the monkeys will not write the\ncode.\n\n\n### Command Options\n\nAll of the commands (`see`, `hear`, `do`) have some common options and\nhave the same argument pattern:\n\n```bash\nmonkey [options] \u003ccommand\u003e [path...]\n```\n\nWhere `[path...]` is any number of paths to files or directories to limit the\nscope of the command to. If no files are provided, the scope is the entire\nproject.\n\nFor example, using the `monkey see ./foo` command will only read, index and\nreason about code in the `foo` directory. Shared vector databases will still\nbe updated.\n\nUsing `monkey hear ./foo` will place that feedback in the context of the `foo`\ndirectory. This is useful for providing feedback on specific parts of the\ncodebase.\n\nWith `monkey do ./foo` the monkeys will only edit the `foo` directory.\n\nEach command also has the following options:\n\n* `--monkey`: The name of the monkey to use. If not provided, all monkeys will\n    be used.\n\n\n## Monkeyfile\n\nYou describe your project and how the monkeys will code using a `Monkeyfile`.\n\nThis file is written in YAML and contains the following keys:\n\n- `name`: The name of the project. This is optional and will be derived from the\n  directory name if not provided.\n\n- `model`: The default model to use for the monkeys. This can be any model\n    configured with Ollama. By default `llama3-8b` is used.\n\n- `ignore`: A list of files that the monkeys will ignore entirely. These files\n    will not be read or affected by other commands. The files are specified as\n    strings which may also include glob patterns, e.g. `[\"src/main.py\",\n    \"src/foo/*.py\"]`.\n\n- `protected`: A list of files that the monkeys are allowed to read but cannot\n    make changes to. The files are specified as strings which may also include\n    glob patterns, e.g. `[\"src/main.py\", \"src/foo/*.py\"]`. This is optional.\n\n- `monkeys`: A dictionary of monkeys that will be coding in your project. The\n    keys are the names of the monkeys and the values are dictionaries with the\n    keys and values described below. By default there is a single monkey named\n    `abu` that can code in any language without specialization in any specific\n    tasks or part of the codebase.\n    \n    - `languages`: A list of languages the monkey can code in. The monkeys will\n        only be able to code in these languages. The languages are specified as\n        strings, e.g. `[\"python\", \"java\"]`. By default the monkey can code in\n        any language.\n    \n    - `model`: The specific model to use for this monkey as an override for the\n        project default.\n    \n    - `prompt`: An extra string that is provided to the monkey when they are\n        coding. This can be used to provide additional context or instructions\n        to the monkey. By default the prompt is empty.\n\n    - `scope`: A list of files that the monkey can edit. The files are specified\n        as strings which may also include glob patterns, e.g. `[\"src/main.py\",\n        \"src/foo/*.py\"]`. By default the monkey can edit any file in the\n        project.\n\n### Access\n\nMonkeys are not granted access to the `Monkeyfile` itself.\n\n## Monkeydream\n\nMonkeydream is the method of translating source files into descriptions of the\nfunctionality that the code provides and the reverse. This is different than\nsimply converting that code to an embedding directly, since searching directly:\n\n - Finds code that is nearby in embedding space, but doesn't provide the same\n   functionality.\n - Doesn't handle different implementations of the same functionality.\n\nThis is done by using LLMs to generate a description of the code that\nis stored in a vector database. Later we can use the vector database to find\ncode that provides that functionality.\n\n## Monkeytrip\n\nMonkeytrip is the method of increasing and decreasing the description\nspecificity allowing for retrieval of code that may provide similar\nfunctionality.\n\nAs an example, if the description is `\"a function that reads a file\"` we can\nincrease the specificity to `\"a function that reads a file and returns the\ncontents as a string\"` or decrease the specificity to `\"a function that reads a\nfile and returns the contents as a list of lines\"`.\n\nWhen enumerating the possibilities to code, the monkeys can use this to find or\ndream code that is similar but may need to be adjusted to fit the current\ncontext.\n\n## Monkeybars\n\nMonkeybars is an instrumentation and testing framework to improve\ndiscoverability. By giving better feedback to the monkeys about why the code is\nfailing beyond basic syntax errors they can learn faster and write better code.\n\nThese are designed to be:\n\n * Minimally intrusive as to not warp the monkeys understanding of the code.\n * Quick and easy to write as they are used to transfer knowledge to the\n   monkeys.\n\nA common instrumentation would be modifying the environment to fail fast instead\nof waiting for a network timeout. Another instrumentation might be a safeguard\nto avoid working with files that are too large.\n\n## Monkeymap\n\nA *Monkeymap* stores how monkeys understand and write code. It's composed of the\nvector databases and metadata beyond. It can be specific to a project or shared\nacross multiple projects.\n\nA Monkeymap can be exported into a `.monkeymap` file, which is a compressed\narchive of all the data in a standalone file.\n\n## License\n\nMonkey is licensed under the MIT license. See the [LICENSE](/LICENSE.md) file\nfor more information. This is a permissive license that allows you to use,\nmodify, and distribute the software.\n\n## Contributing\n\nContributions are welcome! Fork the repository and submit a pull request.\n\nLooking for something to jump in on? Consider looking at issues with these\nlabels:\n\n - [Planning Issues] - Issues that are being prepared for implementation. This\n    is a good place to start if you want to get a feel for the project. It's\n    where contributors transform ideas into actionable tasks.\n  \n  - [Ready Issues] - Issues that are ready to be worked on. These are well\n    defined and have a clear path to completion. This is a good place to start\n    if you want to dive right in and know the underlying technologies.\n\n## Acknowledgements\n\nMonkey was originally developed by [Kristopher Gindlesperger].\n\nMeta trained LLaMA and made it available under a permissive license. The cost of\ntraining these models is exorbitant.\n\nThanks to the authors and contributors of [Ollama]. This project and its\ncommunity make it possible to run any model on any hardware.\n\nThanks to the authors and contributors of [ChromaDB]. This project allows for\nthe storage and retrieval of embeddings in a simple and efficient manner.\n\n[Ollama]: https://ollama.com\n[ChromaDB]: https://docs.trychroma.com\n[Python]: https://www.python.org\n[SQLite]: https://www.sqlite.org\n[Infinite Monkey Theorem]: https://en.wikipedia.org/wiki/Infinite_monkey_theorem\n[Kristopher Gindlesperger]: https://kgindle.com\n[Monkany Labs]: https://monkany.com\n[Monkeyfile]: #monkeyfile\n[Planning Issues]: https://github.com/kgindle/monkey/labels/planning\n[Ready Issues]: https://github.com/kgindle/monkey/labels/ready\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgindle%2Fmonkey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkgindle%2Fmonkey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkgindle%2Fmonkey/lists"}