AI eXecutor

AI eXecutor (aix) - Your AI butler that lives in the terminal and doesn't judge your code

What is this sorcery?

aix (AI eXecutor) is like having a really smart intern who lives in your terminal and can:

• Read your mind (via prompts)
• Execute your commands (safely!)
• Talk to AI gods (OpenAI, Anthropic, OpenRouter)
• Generate weekly reports (with the new --weekly-report flag!)
• Never asks for coffee breaks (because it's code)

Why should I care?

Because typing the same prompts into ChatGPT over and over is so 2023. Now you can:

# Instead of copy-pasting into a browser...
aix run code-review --param code="def add(a,b): return a+b"  # Streaming enabled by default!

# Instead of manually writing commit messages...
aix run commit-msg  # Commands enabled by default!

# Instead of explaining your code to rubber ducks...
aix run explain-code --param file="main.py" --debug  # Show what's happening under the hood

Quick Start (a.k.a. "I have 5 minutes")

Step 1: Install (Choose your fighter)

# Option A: The Cool Kid Way (uv)
uv tool install aix --from git+https://github.com/bhadzhiev/AIeXporter.git

# Option B: The "I still use pip" way
pip install git+https://github.com/bhadzhiev/AIeXporter.git

# Option C: The "I like to suffer" way
# (clone, install deps, etc... see [Installation Guide](docs/INSTALLATION.md))

Step 2: Get an API Key (a.k.a. "Pay the AI tax")

# OpenRouter = 100+ models, free tier available
aix api-key openrouter

# OpenAI = Premium experience, costs money
aix api-key openai

# Anthropic = Claude, also costs money
aix api-key anthropic

# Custom providers get stored with custom: prefix
aix api-key custom:moonshot

Step 3: Actually use it

# Create a prompt template
aix create roast "Roast this {language} code mercilessly:\n{code}"

# Run it (dry run first because we're cowards)
aix run roast --param language=python --param code="print('hello world')" --dry-run

# Run it for real (brace yourself) - streaming is default now!
aix run roast --param language=python --param code="print('hello world')"

Features that will make you go "Ooooh" ✨

Feature	Description	Why it's cool
🔄 Streaming by Default	Real-time responses	See AI thinking in real-time
🐛 Debug Mode	--debug shows internals	See generated prompts and command outputs
📁 Collections-Only Storage	XML-based template organization	Everything is organized, no loose files
⚡ Dynamic Templates	{variables} + $(commands)	Your prompts can now read your system
📚 Template Collections	Organize prompts into groups	Work with focused sets of templates
🌐 GitHub Integration	Import collections from repos	Share collections with the community
🤖 Multi-AI Support	OpenRouter, OpenAI, Anthropic	When one AI is down, use another
🔒 Safety First	Allowlisted commands only	No rm -rf / accidents
🚀 Auto-upgrade	Self-updating tool	Future-you will thank present-you
✅ Auto-complete	Tab completion everywhere	Because typing is hard

Real-world examples (a.k.a. "Show me the money")

The "I'm too lazy to write commit messages" prompt

aix create commit "Write a commit message:\n\nChanges:\n$(git diff --staged)\n\nBe concise, follow conventional commits."

# Then just run (commands enabled by default now!):
aix run commit

The "Explain this mess" prompt

aix create explain "Explain this {language} code like I'm 5:\n\n{code}\n\nFocus on:\n- What it does\n- Why it might exist\n- Potential improvements"

# Usage (streaming by default):
aix run explain --param language=python --param code="$(cat main.py)"

The "Roast my code" prompt

aix create roast "Roast this {language} code:\n\n{code}\n\nBe savage but helpful. Include:\n- Style violations\n- Performance issues\n- Why the junior dev who wrote this should feel bad"

The "System status report" prompt

aix create sys-report "Generate a system status report:\n\n- Host: $(hostname)\n- User: $(whoami)\n- Uptime: $(uptime)\n- Disk: $(df -h /)\n- Memory: $(free -h)\n- Git status: $(git status --porcelain | wc -l) modified files\n\nMake it sound professional but slightly snarky."

# Then (debug mode shows what commands were executed):
aix run sys-report --debug --dry-run

Documentation (a.k.a. "The boring but necessary stuff")

We've hidden all the boring details in separate files because READMEs should be fun:

• Installation Guide - For when pip install isn't working
• Usage Guide - For when you want to do more than just aix --help
• Template Guide - For when you want to become a prompt wizard
• Custom Providers Guide - For when you want to use local AI models
• API Providers - For when you want to know which AI to bribe
• Command Reference - For when you forget what aix run --param does

Configuration (a.k.a. "Making it yours")

# Check what you've broken
aix config --list

# Set your favorite AI overlord
aix config --set default_provider openrouter

# Make it always upgrade (because updates are cool)
aix config --set auto_upgrade true

# Set your editor (vim vs emacs wars incoming)
aix config --set editor nano  # or vim, or code, or butterfly

Advanced Usage (a.k.a. "Look mom, I'm a hacker")

Streaming responses (enabled by default now!)

aix run my-prompt                    # Streaming on by default
aix run my-prompt --no-stream        # Turn off streaming if needed

Debug mode (see what's happening)

aix run my-prompt --debug            # Show generated prompts and command outputs

Custom models (for the connoisseurs)

aix run my-prompt --provider openai --model gpt-4

Output to file (because copy-paste is so 2022)

aix run my-prompt --output genius-idea.txt

Weekly reports (automated reporting)

# Generate weekly report with auto-generated filename
aix run status-report --weekly-report

# Creates: reports/status-report-week-30.md with metadata
# Includes frontmatter with date, week number, and template info

Multiple parameters (the more the merrier)

aix run complex-prompt --param lang=python --param style=pep8 --param complexity=overkill

Troubleshooting (a.k.a. "It doesn't work!")

Common Issues and Solutions

Problem	Solution
aix: command not found	Try python -m aix.cli --help
No API key found	Run aix api-key openrouter
Command not allowed	Commands are enabled by default, check security patterns
Upgrade failed	Run uv tool install aix --force --from git+https://github.com/bhadzhiev/AIeXporter.git
It still doesn't work	Have you tried turning it off and on again?

Getting Help

# The magic help command
aix --help

# Command-specific help
aix run --help
aix create --help

# If all else fails, there's always Stack Overflow

Examples Gallery

0. Custom AI Providers Example

# Add local Ollama for free local AI
aix provider add "ollama" "http://localhost:11434/v1" --model "llama3.2"

# Add custom hosted model
aix provider add "custom-api" "https://my-api.example.com/v1" \
  --model "my-model" \
  --header "X-API-Key:secret"

# Use custom provider (note the custom: prefix)
aix run my-prompt --provider custom:ollama --execute

1. The "I'm a DevOps engineer" prompt

aix create deployment "Create a deployment script for {app_name}:\n\nApp type: {app_type}\nEnvironment: {environment}\nCurrent branch: $(git branch --show-current)\nLast commit: $(git log -1 --pretty=%s)\n\nInclude:\n- Docker setup\n- Environment variables\n- Health checks\n- Rollback strategy"

2. The "I need to sound smart in meetings" prompt

aix create meeting-prep "Prepare talking points for meeting about {topic}:\n\nContext:\n$(git log --oneline -10)\n$(find . -name "*.py" -mtime -7 | head -5)\n\nMake me sound like I know what I'm doing."

3. The "Generate excuses" prompt

aix create excuse "Generate a technical excuse for why {feature} is delayed:\n\nCurrent blocker: {blocker}\nTeam size: $(whoami) # it's just me\nDeadline: {deadline}\n\nMake it sound technical but not my fault."

4. The "Organize your prompts" workflow

# Create a collection for your project
aix collection-create "web-project" --description "Prompts for web development tasks"

# Add related prompts to the collection
aix collection-add code-review
aix collection-add deployment
aix collection-add meeting-prep

# Load the collection and work with just those prompts
aix collection-load web-project
aix list  # Shows only web-project prompts

# When you need all prompts back
aix collection-unload

# Share your collections with the world (or import from others)
aix collection-export web-project -o ~/sharing/
aix collection-import-repo https://github.com/bhadzhiev/AIeXpoerterCollections.git

Buy Me a Coffee

If this tool saves you from writing one more commit message manually, consider buying me a coffee:

Revolut: @bozhide29n

Every coffee helps me write more sarcastic error messages.

Testimonials

"I used to spend hours writing commit messages. Now I spend hours debugging why the AI's commit messages don't make sense." - A satisfied user

"It's like having a junior developer who never sleeps and doesn't complain about my code style." - Tech Lead

"The auto-upgrade feature means I never have to manually update tools again. My laziness has reached new heights." - DevOps Engineer

License

MIT License - do whatever you want, just don't blame me when your AI-generated commit messages confuse your team.

Contributing

Found a bug? Want to add a feature? Have a better joke for the README?

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Test it (please)
5. Submit a PR

Bonus points if your commit messages are generated by this tool.

---

Made with love by someone who got tired of copy-pasting prompts into ChatGPT

Now stop reading and go automate something!