JugaadAgent 🔧

जुगाड़ (joo-gaad) - the Indian art of resourceful problem-solving.

Type what you want in plain English. JugaadAgent generates the shell command, checks the risk, and retries with real diagnostics when it fails. Runs entirely on your machine via Ollama - no cloud, no API costs.

Install

pip install jugaad-agent
ollama pull qwen2.5-coder:latest

Or use pipx install jugaad-agent if you prefer isolated CLI tools.

Requirements: Linux (Ubuntu recommended), Python 3.10+, Ollama

Usage

jugaad "free port 8080"
jugaad "find files larger than 100MB in /var/log"
jugaad "install and start nginx" --dry-run
jugaad "something is eating my disk - figure out what"

Short alias: jaa works everywhere jugaad does.

How it works

memory → generator → guardrail → executor
           ↑                         │
           └───── fail + diagnose ───┘

When a command fails, JugaadAgent doesn't retry blindly. It runs lsof, checks for missing binaries, reads permission errors - then sends that context back to the model before retrying.

Safety

JugaadAgent runs real shell commands on your machine.

Flags:

• --dry-run - generate without executing
• --yes / -y - skip approval prompts (use carefully)
• --max-retries - hard cap on self-heal loops (default: 3)

Options

jugaad "task" -m llama3.2:3b      # set model (saved for future runs)
jugaad "task" --max-retries 5
jugaad "task" --dry-run
jugaad "task" --yes
jugaad --version

Model selection priority

1. -m / --model flag (persisted to ~/.config/jugaad-agent/)
2. JUGAAD_MODEL env (one-time override, not saved)
3. Saved preference from a previous -m
4. Built-in default: qwen2.5-coder:latest

Environment variables

Workspace rules

Add .agent_rules.md to any project directory - JugaadAgent reads it on every run. Use it for preferred tools, things to avoid, or project-specific context.

Example:

- Prefer `rg` over `grep` when searching code
- Use `uv` instead of `pip` for Python installs
- Never delete anything in `/data/production`

See .agent_rules.md.example for more ideas.

Development

git clone https://github.com/dhruva3223/jugaad-agent.git
cd jugaad-agent
pip install -e ".[dev]"

Build for PyPI:

rm -rf dist/ build/ src/*.egg-info
python -m build
twine check dist/*
twine upload dist/*

License

MIT - see LICENSE

Contributing

Issues and PRs welcome at github.com/dhruva3223/jugaad-agent