{"id":37230049,"url":"https://github.com/djsoftware1/runai","last_synced_at":"2026-01-15T03:36:24.949Z","repository":{"id":214872175,"uuid":"729874587","full_name":"djsoftware1/runai","owner":"djsoftware1","description":"AI terminal integration. Multi-purpose, cross-platform task automation \u0026 execution Python tool, supporting AutoGen multi-agents, for AI/LLM \u0026 other kinds of tasks. Created by David Joffe @davidjoffe. Business Source License. NOTE For some tasks this tool may modify files. Use with caution in a sandbox copy of your files 1st","archived":false,"fork":false,"pushed_at":"2026-01-11T20:28:01.000Z","size":403,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-11T23:05:04.817Z","etag":null,"topics":["agents","ai","aider","anthropic","autogen","automation","bsl","business","command-line","framework","gemini","llm","lmstudio","ollama","python","terminal","toml"],"latest_commit_sha":null,"homepage":"https://djoffe.com/dj-software/runai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/djsoftware1.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-10T16:14:11.000Z","updated_at":"2026-01-11T20:28:04.000Z","dependencies_parsed_at":"2026-01-11T21:22:13.460Z","dependency_job_id":null,"html_url":"https://github.com/djsoftware1/runai","commit_stats":null,"previous_names":["djsoftware1/runai"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/djsoftware1/runai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djsoftware1%2Frunai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djsoftware1%2Frunai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djsoftware1%2Frunai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djsoftware1%2Frunai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/djsoftware1","download_url":"https://codeload.github.com/djsoftware1/runai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djsoftware1%2Frunai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agents","ai","aider","anthropic","autogen","automation","bsl","business","command-line","framework","gemini","llm","lmstudio","ollama","python","terminal","toml"],"created_at":"2026-01-15T03:36:24.455Z","updated_at":"2026-01-15T03:36:24.941Z","avatar_url":"https://github.com/djsoftware1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# runai: DJ Software Task Execution and Automation Framework\n\n* [runai homepage](https://djoffe.com/dj-software/runai/)\n\nA kind of integrated 'AI extension' of your terminal or command prompt.\n\nGeneral AI/LLM-driven task execution and automation tool for tasks such as code refactoring (or many other tasks, including non-coding-related tasks), supporting AutoGen.\n\n“Any project you’re working on, runai becomes another tool in your terminal.”\n\n**Use also straight from VS Code and Cursor terminal:**\n\n![runai screenshot by David Joffe and icon symbol](https://djoffe.com/dj-software/runai/media/runai_crop_center_logo.png)\n\n**Cross-platform:** Integrates into command-line for Windows command prompt, git bash, Linux, or macOS terminal.\n\nSupports either OpenAI or your own custom AI instances (for example your own LiteLLM server(s)).\n\n### Example:\n\n```\nrunai -t \"Write a Python script that can check daily for updated exchange rate for USD, EUR\"\n```\nUse `-t \"task\"` to specify the task to be done.\n\n## Help and Examples - Getting Started\n\n```runai -h``` **Show full main usage help**\n\n```runai --version``` **Show version**\n\n```runai --showsettings``` **Just show settings and exit**\n\n**Example:**\n```\nrunai --gpt4 -t \"Repeat the word coffee five times\"\n\nrunai -t \"Repeat the word coffee five times, then help cure aging\"\n```\n\n### Common settings quick-reference\n```\nrunai -h  show full help  --showsettings  just show settings  --version  show version number  --dryrun \n      -t \"TASK\" task instructions for LLM to do  -tf \"TaskFile\" task file to load (default runai.autotask.txt)\n      -m \"MODEL\" select model  -p \"PROJECT-NAME\"  -4 use gpt-4  --o1-mini  --o1-preview\n      -f \"FOLDER\"  set work-folder   subcommands (refactor,build,create,createfrom,modify) ...\n      -i \"InputFile\" to batch-run task on all lines, with substitution. default=input.txt\n      -a FileAttachment [-a ...]\n      -q No-output-files mode\n```\n```\nUSAGE: runai (or python main.py) [taskfile] [targetfolder] [settings.py]\n```\n\nYou can use \"--showsettings\" to just check the settings before running! For example:\n```\nrunai --showsettings refactor -w main.py\n```\n\n### New Command-Line Option: Attach\n#### Use the `--attach` or `-a` Option\n\nRunai now supports attaching files to tasks using the `--attach` or `-a` option. This feature enables you to include images and various document types (PDF, Word, etc.) as attachments, as long as the selected backend or model supports this feature.\n\n**Example:**\n```\nrunai -t \"Analyze the attached image for visual elements\" --attach example_image.png\n```\nor\n```\nrunai -t \"Parse the PDF document for key insights\" --attach document.pdf\n```\n\nAttachment support is particularly useful for tasks involving image processing or extracting information from documents. \n\n### Common Use Cases for Attachments\n1. **Image Analysis:**\n   - **Command:** \n   ```\n   runai -t \"What objects do you see in the attached image?\" -a sample_image.jpg\n   ```\n   \n2. **Document Processing:**\n   - **Command:** \n   ```\n   runai -t \"Summarize the attached Word document\" --attach report.docx\n   ```\n\n3. **Data Extraction:**\n   - **Command:** \n   ```\n   runai -t \"Write a brief on the key points from the attached PDF\" --attach notes.pdf\n   ```\n\n### Subcommand Help\n\n* **create**: Create new file(s) mode: `runai create`\n* **refactor**: Refactor existing files mode: `runai refactor`\n\nUse `runai __subcommand__ -h` to show usage help for subcommands (create, refactor, build, createfrom, modify)\n```\nrunai create -h\n=\u003e usage: main.py create [-h] [-o OUT [OUT ...]]\n\nrunai refactor -h\n=\u003e usage: runai refactor [-h] [-r FIND_REGEX] [--find-text FIND_TEXT]\n   [-w WILDCARDS [WILDCARDS ...]][--replace-with REPLACE_WITH] [-s SEND [SEND ...]]\n```\n\n### Testing and Simple Commands\nTry a simple test to see if it's working: \n```\nrunai -4 -t \"Hi, can you help me?\"\n```\n\n### runai Environment Variables (optional)\n\nYou may optionally specify settings in environment variables: RUNAI_MODEL, RUNAI_TASKFILE, RUNAI_TASK, RUNAI_PROJECT. (Options specified on the command line will override these.)\n\n### Selecting Model\n\nOptions for selecting the model to use:\n\n```\n   -m \"model\" OR --model \"model\" - use \"model\"\n   -m \"ollama/deepseek-r1:8b\"\n   -m \"openai/gpt-4o-mini\"\n   -m \"lmstudio/phi-3\"\n   -m \"gemini/gemini-2.5-flash\"\n   -m \"anthropic/claude-3-haiku\"\n   -m \"xai/grok-3-mini\"\n   -m \"gpt-4.1-mini\"\n   -m \"gpt-4.1-nano\"\n   -m \"gpt-4.1\"\n   -4 or --gpt4 - use gpt4\n   -3 or --gpt3 - use gpt3 (deprecated)\n   --o1-mini - use o1-mini\n   --o1-preview - use o1-preview\n```\n\n**Example:** `runai --openai -t \"Write a short story about cats\"`\n\n### Project Name\n\nUse --project or -p to specify a project name, which will be used when auto-generating output such as automatically-generated output files and folder name.\n\n```sh\nrunai -p \"coding\" -t \"Write a C++ vec3d class\"\n\nrunai -p \"Thesis\" -t \"Help me brainstorm ideas on my thesis research about the following subject: ...\"\n```\n\nGenerated output will be placed under a subfolder of the given project name.\n\n### Selecting Backend\n\nOptions for selecting the backend\n\n```\n   --openai Use OpenAI backend directly (without AutoGen) for tasks\n\n   --djchat Use djchat/djchatbot backend (without AutoGen) if available\n```\n\n#### Testing\n\n```\n   --dummy Special 'dummy' backend for testing\n\n   --echo Echo mode: Dummy backend just sends back task string as \"result\" for testing\n```\n\n**Note:** For some tasks, this tool can modify files, so use with caution. Always backup all your data first, work in a 'sandbox' copy, and check all changes. Test things first. Use at your own risk.\n\n## License\n\nrunai is source-available software licensed under the Business Source License (BSL) 1.1.\n\nFree for personal, educational, research, and evaluation use.\nCommercial use requires a separate license.\n\nSee the [LICENSE](LICENSE.md) file for details.\n\n## Installation\n\nFirst, either download runai (as a zip), or clone this GitHub repo: `$ git clone https://github.com/djsoftware1/runai`\n\nThen do (preferably create an env and activate it, then):\n\n```\n$ pip install . \nOR if you are using uv:\n$ uv pip install .\n```\n\nThat's it! If you activate your env, you should now be able to use runai from anywhere on your command-line, including integrated terminal windows in IDEs like VS Code or Cursor.\n\n### Old way:\n\nThen install requirements (you may use an env, though may be useful to install globally to more easily run \"runai\" from anywhere on command line):\n\n```\npip install -r requirements.txt\n```\n\nTo run:\n\n```\n$ runai\n\nOr (old way): python main.py\n```\n\nIf you follow the instructions here to add this to your system PATH, then you can just type \"runai\" from anywhere. (Otherwise, use \"./runai\" or a full path to run.)\n\nIf using OpenAI, then place your configuration with API key in OAI_CONFIG_LIST\n\n### PATH Setup (Optional - not necessary if using pip install as above)\n\nrunai \"works best\" if you optionally add to your system PATH - then you can just type \"runai\" on the command line from any folder to run - potentially very powerful.\n\nOn Windows, you can use the system Environment Variables dialog to add runai to PATH. (git bash _should_ automatically 'inherit' this for its PATH.)\n\nFor Linux/macOS (or also git bash), add a line like this in e.g. your **.bashrc** or zshrc startup file to add it to PATH on bash startup:\n\n``` sh\n    export PATH=\"/c/src/runai:$PATH\"\n```\n(If, for example, you did 'git clone' this project into your, say, \"/c/src\" folder.)\n\n(\"runai\" is just a small wrapper for 'python main.py'.)\n\n## Simple Test\n\nTry a simple test like this to see if it's working: \n```\n    runai -4 -t \"Hi, can you help me?\"\n```\n\n## Show Settings and Exit\n\n```\nrunai -c\nrunai --showsettings\n\nOR e.g. with a task settings:\n\nrunai --showsettings refactor -w \"*.cpp\" \"*.h\"\n\nrunai -tf mytask.txt --showsettings refactor -w \"*.cpp\" \"*.h\"\n\n# Straight-forward non-AI replace:\nrunai refactor -w \"main.py\" -r \"findme\" --replace-with \"foo\"\n\netc.\n```\n\n### Task files and runai.autotask.txt\n\nBy default, it looks for a file named \"runai.autotask.txt\" in the folder you run it, and if found, automatically loads the task from that file.\n\nOr, you can specify a task file with \"-tf\" or \"--taskfile\" (or task string with -t).\n\nIf no autotask is found and no task or taskfile passed as a parameter, it will ask for a task.\n\n## Custom LiteLLM Server:\n\nIt is recommended to use a separate Python environment for litellm to avoid dependency issues.\n\n```\n# Optional if want to run local AI server:\n$ pip install litellm (or: python3 -m pip install litellm)\n\nAnd possibly also:\n\n$ pip install litellm[proxy]\n```\n\nThen e.g. 'ollama pull codellama' and 'litellm --model ollama/codellama'\n\nSome kinds of tasks don't require AI at all and are just done locally, e.g. a refactor straightforward regex replace.\n\n## Multi-line input replacements\n\nIf feeding an input list, you can use \"{$1}\" in the task string to replace it with the line contents. For example, if your input lines are:\n\n```\nVec2d\nVec3d\nMatrix4d\n```\n\nYou can use e.g. \"Generate a class called {$1} with implementation\", etc.\n\nThe special variable \"{$line}\" can be replaced with the original line number of the input file.\n\n* {$line} Replace with the current input line number in task string for multi-line input\n* {$date} Replace with the current date (UTC) in task string\n* {$time} Replace with the current time (UTC) in task string\n* {$datetime} Replace with the current date and time (UTC) in task string (YYYY-MM-DD HH-MM-SS)\n\n## To try force use of GPT3, GPT4, o1-mini or other preferred model:\n\nOpenAI/AutoGen tasks: Provided your OAI_CONFIG_LIST is set up correctly, you can use the command-line parameters described above under the 'Help' section to select any preferred model.\n\n### Design thoughts on main task types:\n\n## Main Task Types:\n\n1. **Code Generation**\n   - Add new code, such as classes, functions, or entire modules.\n   - Example: Automatically generate a new Vec3d class in vec3d.h/cpp files.\n\n2. **Code Enhancement**\n   - Extend existing files by adding new functionalities, methods, or classes.\n   - Implement stubs or abstract methods.\n   - Example: Add new methods to an existing class or implement TODOs.\n\n3. **Code Refactoring**\n   - Modify existing code to improve structure, performance, readability, or maintainability without changing its external behavior.\n   - Example: Refactor specific patterns, optimize algorithms, or update to newer syntax.\n\n```\n# Use \"--showsetttings\" to just check the settings before run\nrunai --showsettings refactor -w main.py\nrunai refactor -w src/MyFile.cpp\n\nrunai --showsettings refactor -w \"*.cpp\" \"*.h\"\nrunai refactor -w \"*.cpp\" \"*.h\"\n\nrunai refactor -w src/MyFile.cpp\n\nrunai -t \"Update this README with the latest new features\" -p edits modify -e README.md\n```\n\n4. **Build and Test Automation**\n   - Compile code, run build processes, and execute automated tests.\n   - Analyze build logs and test reports for errors or warnings.\n   - Example: Run unit tests, integration tests, and analyze results.\n\n5. **Code Analysis and Linting**\n   - Perform static code analysis for potential issues.\n   - Enforce coding standards and style guides.\n   - Example: Run linters and format code according to PEP 8 for Python.\n\n6. **Documentation Generation**\n   - Auto-generate documentation from code comments and docstrings.\n   - Keep documentation in sync with code changes.\n   - Example: Generate API documentation using tools like Doxygen or Sphinx.\n\n7. **Dependency Management**\n   - Update or manage external libraries and dependencies.\n   - Ensure compatibility and security of dependencies.\n   - Example: Update packages to the latest versions while ensuring compatibility.\n\n8. **Version Control Operations**\n   - Automate commits, merges, branches, and other version control operations.\n   - Handle version tagging and release management.\n   - Example: Auto-commit changes after successful tests and linting.\n\n9. **Deployment and Release Automation**\n   - Automate the deployment of code to production or staging environments.\n   - Manage release cycles and deployment schedules.\n   - Example: Automatically deploy code to a staging server after passing CI/CD pipelines.\n\n## Examples with Attachments\n\n```\nrunai -4 -tf /c/runai/tasks/copyright/task.txt -f ./cppcode_folder/ -s /c/runai/tasks/copyright/settings.py refactor -w \"*.cpp\"\n\nrunai -t \"Analyze the attached image\" --attach sample_image.jpg\n\nrunai -t \"Summarize the attached PDF document\" -a report.pdf\n```\n\n## Notes on caching\n\nNote that AutoGen caches results, and sometimes this may cause issues where something appears to not work when it is working. Try removing the cache ('rm -rf .cache') at times and see if that helps.\n\n## About\n\nMulti-purpose automation framework, optionally with AutoGen multi-agents, for AI/LLM and other task automation, created by David Joffe @davidjoffe (beta/early dev)\n\nOther potential names: dj-runAI, or djrun, or perhaps 'dj-run-tasks' (to reflect that not all tasks are AI-based).\n\n## Copyright\n\nThis project Copyright (C) David Joffe and [DJ Software](https://djoffe.com/dj-software/) 2023-2026\n\n\"**DJ Software**\" is just short for \"David Joffe Software\", and is a name I created to place some of my software under (and of 1. a potential entity, and 2. of this [GitHub organization \"djsoftware1\" I created for DJ Software](https://github.com/djsoftware1/)).\n\nSee also [djoffe.com/dj-software/](https://djoffe.com/dj-software/)\n\n- [David Joffe](https://davidjoffe.github.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjsoftware1%2Frunai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjsoftware1%2Frunai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjsoftware1%2Frunai/lists"}