Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/djsoftware1/runai

AI terminal integration. Multi-purpose, cross-platform task automation & execution Python tool, supporting AutoGen multi-agents, for AI/LLM & 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
https://github.com/djsoftware1/runai

agents ai aider anthropic autogen automation bsl business command-line framework gemini llm lmstudio ollama python terminal toml

Last synced: 3 months ago
JSON representation

AI terminal integration. Multi-purpose, cross-platform task automation & execution Python tool, supporting AutoGen multi-agents, for AI/LLM & 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

Awesome Lists containing this project

README 

          
# runai: DJ Software Task Execution and Automation Framework



* [runai homepage](https://djoffe.com/dj-software/runai/)



A kind of integrated 'AI extension' of your terminal or command prompt.



General 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.



“Any project you’re working on, runai becomes another tool in your terminal.”



**Use also straight from VS Code and Cursor terminal:**



![runai screenshot by David Joffe and icon symbol](https://djoffe.com/dj-software/runai/media/runai_crop_center_logo.png)



**Cross-platform:** Integrates into command-line for Windows command prompt, git bash, Linux, or macOS terminal.



Supports either OpenAI or your own custom AI instances (for example your own LiteLLM server(s)).



### Example:



```

runai -t "Write a Python script that can check daily for updated exchange rate for USD, EUR"

```

Use `-t "task"` to specify the task to be done.



## Help and Examples - Getting Started



```runai -h``` **Show full main usage help**



```runai --version``` **Show version**



```runai --showsettings``` **Just show settings and exit**



**Example:**

```

runai --gpt4 -t "Repeat the word coffee five times"



runai -t "Repeat the word coffee five times, then help cure aging"

```



### Common settings quick-reference

```

runai -h  show full help  --showsettings  just show settings  --version  show version number  --dryrun 

      -t "TASK" task instructions for LLM to do  -tf "TaskFile" task file to load (default runai.autotask.txt)

      -m "MODEL" select model  -p "PROJECT-NAME"  -4 use gpt-4  --o1-mini  --o1-preview

      -f "FOLDER"  set work-folder   subcommands (refactor,build,create,createfrom,modify) ...

      -i "InputFile" to batch-run task on all lines, with substitution. default=input.txt

      -a FileAttachment [-a ...]

      -q No-output-files mode

```

```

USAGE: runai (or python main.py) [taskfile] [targetfolder] [settings.py]

```



You can use "--showsettings" to just check the settings before running! For example:

```

runai --showsettings refactor -w main.py

```



### New Command-Line Option: Attach

#### Use the `--attach` or `-a` Option



Runai 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.



**Example:**

```

runai -t "Analyze the attached image for visual elements" --attach example_image.png

```

or

```

runai -t "Parse the PDF document for key insights" --attach document.pdf

```



Attachment support is particularly useful for tasks involving image processing or extracting information from documents. 



### Common Use Cases for Attachments

1. **Image Analysis:**

   - **Command:** 

   ```

   runai -t "What objects do you see in the attached image?" -a sample_image.jpg

   ```

   

2. **Document Processing:**

   - **Command:** 

   ```

   runai -t "Summarize the attached Word document" --attach report.docx

   ```



3. **Data Extraction:**

   - **Command:** 

   ```

   runai -t "Write a brief on the key points from the attached PDF" --attach notes.pdf

   ```



### Subcommand Help



* **create**: Create new file(s) mode: `runai create`

* **refactor**: Refactor existing files mode: `runai refactor`



Use `runai __subcommand__ -h` to show usage help for subcommands (create, refactor, build, createfrom, modify)

```

runai create -h

=> usage: main.py create [-h] [-o OUT [OUT ...]]



runai refactor -h

=> usage: runai refactor [-h] [-r FIND_REGEX] [--find-text FIND_TEXT]

   [-w WILDCARDS [WILDCARDS ...]][--replace-with REPLACE_WITH] [-s SEND [SEND ...]]

```



### Testing and Simple Commands

Try a simple test to see if it's working: 

```

runai -4 -t "Hi, can you help me?"

```



### runai Environment Variables (optional)



You may optionally specify settings in environment variables: RUNAI_MODEL, RUNAI_TASKFILE, RUNAI_TASK, RUNAI_PROJECT. (Options specified on the command line will override these.)



### Selecting Model



Options for selecting the model to use:



```

   -m "model" OR --model "model" - use "model"

   -m "ollama/deepseek-r1:8b"

   -m "openai/gpt-4o-mini"

   -m "lmstudio/phi-3"

   -m "gemini/gemini-2.5-flash"

   -m "anthropic/claude-3-haiku"

   -m "xai/grok-3-mini"

   -m "gpt-4.1-mini"

   -m "gpt-4.1-nano"

   -m "gpt-4.1"

   -4 or --gpt4 - use gpt4

   -3 or --gpt3 - use gpt3 (deprecated)

   --o1-mini - use o1-mini

   --o1-preview - use o1-preview

```



**Example:** `runai --openai -t "Write a short story about cats"`



### Project Name



Use --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.



```sh

runai -p "coding" -t "Write a C++ vec3d class"



runai -p "Thesis" -t "Help me brainstorm ideas on my thesis research about the following subject: ..."

```



Generated output will be placed under a subfolder of the given project name.



### Selecting Backend



Options for selecting the backend



```

   --openai Use OpenAI backend directly (without AutoGen) for tasks



   --djchat Use djchat/djchatbot backend (without AutoGen) if available

```



#### Testing



```

   --dummy Special 'dummy' backend for testing



   --echo Echo mode: Dummy backend just sends back task string as "result" for testing

```



**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.



## License



runai is source-available software licensed under the Business Source License (BSL) 1.1.



Free for personal, educational, research, and evaluation use.

Commercial use requires a separate license.



See the [LICENSE](LICENSE.md) file for details.



## Installation



First, either download runai (as a zip), or clone this GitHub repo: `$ git clone https://github.com/djsoftware1/runai`



Then do (preferably create an env and activate it, then):



```

$ pip install . 

OR if you are using uv:

$ uv pip install .

```



That'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.



### Old way:



Then install requirements (you may use an env, though may be useful to install globally to more easily run "runai" from anywhere on command line):



```

pip install -r requirements.txt

```



To run:



```

$ runai



Or (old way): python main.py

```



If 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.)



If using OpenAI, then place your configuration with API key in OAI_CONFIG_LIST



### PATH Setup (Optional - not necessary if using pip install as above)



runai "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.



On Windows, you can use the system Environment Variables dialog to add runai to PATH. (git bash _should_ automatically 'inherit' this for its PATH.)



For 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:



``` sh

    export PATH="/c/src/runai:$PATH"

```

(If, for example, you did 'git clone' this project into your, say, "/c/src" folder.)



("runai" is just a small wrapper for 'python main.py'.)



## Simple Test



Try a simple test like this to see if it's working: 

```

    runai -4 -t "Hi, can you help me?"

```



## Show Settings and Exit



```

runai -c

runai --showsettings



OR e.g. with a task settings:



runai --showsettings refactor -w "*.cpp" "*.h"



runai -tf mytask.txt --showsettings refactor -w "*.cpp" "*.h"



# Straight-forward non-AI replace:

runai refactor -w "main.py" -r "findme" --replace-with "foo"



etc.

```



### Task files and runai.autotask.txt



By 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.



Or, you can specify a task file with "-tf" or "--taskfile" (or task string with -t).



If no autotask is found and no task or taskfile passed as a parameter, it will ask for a task.



## Custom LiteLLM Server:



It is recommended to use a separate Python environment for litellm to avoid dependency issues.



```

# Optional if want to run local AI server:

$ pip install litellm (or: python3 -m pip install litellm)



And possibly also:



$ pip install litellm[proxy]

```



Then e.g. 'ollama pull codellama' and 'litellm --model ollama/codellama'



Some kinds of tasks don't require AI at all and are just done locally, e.g. a refactor straightforward regex replace.



## Multi-line input replacements



If 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:



```

Vec2d

Vec3d

Matrix4d

```



You can use e.g. "Generate a class called {$1} with implementation", etc.



The special variable "{$line}" can be replaced with the original line number of the input file.



* {$line} Replace with the current input line number in task string for multi-line input

* {$date} Replace with the current date (UTC) in task string

* {$time} Replace with the current time (UTC) in task string

* {$datetime} Replace with the current date and time (UTC) in task string (YYYY-MM-DD HH-MM-SS)



## To try force use of GPT3, GPT4, o1-mini or other preferred model:



OpenAI/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.



### Design thoughts on main task types:



## Main Task Types:



1. **Code Generation**

   - Add new code, such as classes, functions, or entire modules.

   - Example: Automatically generate a new Vec3d class in vec3d.h/cpp files.



2. **Code Enhancement**

   - Extend existing files by adding new functionalities, methods, or classes.

   - Implement stubs or abstract methods.

   - Example: Add new methods to an existing class or implement TODOs.



3. **Code Refactoring**

   - Modify existing code to improve structure, performance, readability, or maintainability without changing its external behavior.

   - Example: Refactor specific patterns, optimize algorithms, or update to newer syntax.



```

# Use "--showsetttings" to just check the settings before run

runai --showsettings refactor -w main.py

runai refactor -w src/MyFile.cpp



runai --showsettings refactor -w "*.cpp" "*.h"

runai refactor -w "*.cpp" "*.h"



runai refactor -w src/MyFile.cpp



runai -t "Update this README with the latest new features" -p edits modify -e README.md

```



4. **Build and Test Automation**

   - Compile code, run build processes, and execute automated tests.

   - Analyze build logs and test reports for errors or warnings.

   - Example: Run unit tests, integration tests, and analyze results.



5. **Code Analysis and Linting**

   - Perform static code analysis for potential issues.

   - Enforce coding standards and style guides.

   - Example: Run linters and format code according to PEP 8 for Python.



6. **Documentation Generation**

   - Auto-generate documentation from code comments and docstrings.

   - Keep documentation in sync with code changes.

   - Example: Generate API documentation using tools like Doxygen or Sphinx.



7. **Dependency Management**

   - Update or manage external libraries and dependencies.

   - Ensure compatibility and security of dependencies.

   - Example: Update packages to the latest versions while ensuring compatibility.



8. **Version Control Operations**

   - Automate commits, merges, branches, and other version control operations.

   - Handle version tagging and release management.

   - Example: Auto-commit changes after successful tests and linting.



9. **Deployment and Release Automation**

   - Automate the deployment of code to production or staging environments.

   - Manage release cycles and deployment schedules.

   - Example: Automatically deploy code to a staging server after passing CI/CD pipelines.



## Examples with Attachments



```

runai -4 -tf /c/runai/tasks/copyright/task.txt -f ./cppcode_folder/ -s /c/runai/tasks/copyright/settings.py refactor -w "*.cpp"



runai -t "Analyze the attached image" --attach sample_image.jpg



runai -t "Summarize the attached PDF document" -a report.pdf

```



## Notes on caching



Note 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.



## About



Multi-purpose automation framework, optionally with AutoGen multi-agents, for AI/LLM and other task automation, created by David Joffe @davidjoffe (beta/early dev)



Other potential names: dj-runAI, or djrun, or perhaps 'dj-run-tasks' (to reflect that not all tasks are AI-based).



## Copyright



This project Copyright (C) David Joffe and [DJ Software](https://djoffe.com/dj-software/) 2023-2026



"**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/)).



See also [djoffe.com/dj-software/](https://djoffe.com/dj-software/)



- [David Joffe](https://davidjoffe.github.io/)