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.

Module	What it does
state.py	Pydantic state + history accumulator
nodes.py	LLM generation + shell execution
guardrails.py	Risk scan + human approval (HITL)
diagnostics.py	Enriches stderr with Ubuntu telemetry
memory.py	Loads .agent_rules.md from working directory
graph.py	LangGraph state machine

---

Safety

JugaadAgent runs real shell commands on your machine.

Risk level	Behavior
LOW	Runs automatically
MEDIUM / HIGH	Stops and asks [Y]es / [N]o / [E]dit before executing

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

Variable	Default	Purpose
JUGAAD_MODEL	(unset)	Override model for this run only
JUGAAD_BASE_URL	http://127.0.0.1:11434	Ollama API endpoint
JUGAAD_MAX_RETRIES	3	Self-heal retry ceiling

---

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