note

GUI Version is in development is the second branch

AI Shell Agent

AI Shell Agent is like an ai shell agent Tell it what you want in plain English. It asks your chosen AI model for the exact command, shows it to you, runs it in cmd.exe or PowerShell, and prints the real output back.

Install

pip install -r requirements.txt

First run

python main.py

The first time you run it (or any time you run python main.py --setup), it will:

1. Ask which provider you want: OpenAI, Anthropic (Claude), Google (Gemini), Ollama (local), or OpenRouter.
2. Ask for your API key (skipped for Ollama — it just needs the local URL, default http://localhost:11434).
3. Call that provider's API to list every model your key can access, and let you pick one from a numbered menu.
4. Ask whether you want a confirmation prompt before each command actually runs.
5. Save everything to config.json

Usage

python main.py                       # interactive chat loop
python main.py --setup               # re-run setup (switch provider/model/key)

Type exit or quit (or Ctrl+C) to leave the interactive loop.

Files

File	Purpose
main.py	Entry point / chat loop
setup_wizard.py	First-run wizard: pick provider, enter key, list & choose model
config_manager.py	Reads/writes ~/config.json
ai_agent.py	Builds the prompt, calls the model, parses the JSON command response
command_executor.py	Actually runs the command via cmd.exe / PowerShell and captures output
providers/	One file per API (OpenAI, Anthropic, Google, Ollama, OpenRouter), all sharing the same Provider interface

Safety note (read this)

This tool executes whatever command the model returns, with your full shell permissions - it does not sandbox, whitelist, or filter commands. That's the point of the tool, but it's worth knowing what that means in practice:

• Confirmation prompt: on by default (require_confirmation: true in the config). It shows you the exact command before running it. You can turn it off in the wizard or by hand-editing the config, but for anything destructive (deleting files, changing permissions, disabling security tooling) you'll want a human in the loop.
• Model mistakes happen. LLMs occasionally hallucinate flags or misread intent, especially on ambiguous phrasing - the confirm step is your real safety net, not a formality.

extra usage info

To use this you need to give the ai more detailed info or prompt for this to work for some tasks this wont work like sending a message or doing multi step tasks because this is not an agent its an automation tool made because AI agents like open claw sends a lot of requests per minute resulting on a crash on free api keys like google ai studio key and open claw isn't usable on free ai api keys so this tool works by sending a very small amount of requests to the api key this sends from 1 to 3 requests maximum so that's why this is the best tools for free users