heal 0.1.23

A Python package for healing and wellness

Heal 🩺

LLM-powered shell error fixing — Your AI assistant for debugging and fixing command-line errors instantly, with built-in privacy protection.

Installation

pip install heal

# With full privacy protection (detect-secrets, presidio, faker, etc.)
pip install heal[privacy]

Quick Start

Complete Setup (Recommended)

# 1. Configure heal (first time only)
heal config

# 2. Test your configuration
heal test

# 3. Initialize bash integration
heal init

# 4. Restart your shell
source ~/.bashrc

# 5. Use heal - just run any command and then heal!
python broken_script.py
heal

Simplest Usage - Just heal

# Run any failing command, then simply run heal
npm install
heal

# Or pipe errors directly
make build 2>&1 | heal

# From error file
heal < error.log

# With privacy protection (anonymize sensitive data)
production_script.py 2>&1 | heal --anonymize

Automatic Mode (with shell integration)

# Initialize bash integration (recommended)
heal init

# This will automatically add to ~/.bashrc
# Or manually add: source ~/.heal/heal.bash

# Restart your shell
source ~/.bashrc

# Now you can run any command and heal will capture it:
your_failing_command
heal

Features

• 🤖 LLM-powered error analysis - Uses GPT models to understand and fix shell errors
• 🔄 Automatic command capture - Shell hook captures last command and output
• 📥 Multiple input methods - Works with stdin, files, or shell hooks
• ⚙️ Configurable models - Support for various LLM providers via litellm
• 🔒 Privacy protection - 6 anonymization backends (regex, detect-secrets, presidio, priv-masker, datafog, faker)
• 🐳 Docker-ready - Full e2e test suite in Docker
• 🚀 Zero-config start - Just run heal after any error

Privacy Protection

Mask sensitive data before it leaves your machine:

# Anonymize secrets, PII, tokens before sending to LLM
production_script.py 2>&1 | heal --anonymize

# Check which backends are active
heal fix --privacy-check

Backend	What it masks	Install
builtin_regex	Emails, phones, IPs, API keys, JWT, PEM, DB passwords	included
detect-secrets	High-entropy strings, cloud keys	pip install detect-secrets
presidio	Names, addresses, dates (NLP, multilingual)	pip install presidio-analyzer
priv-masker	Polish NLP (PESEL, names, addresses)	pip install priv-masker spacy
datafog	Lightweight PII	pip install datafog
faker	Generate realistic fake replacements	pip install faker

Install all at once: pip install heal[privacy]

📚 Documentation

Guide	Description
Quick Start	Get running in 5 minutes
Getting Started	Full setup walkthrough
Configuration Guide	Provider & model setup
Multi-Provider Usage	Switch between LLM providers
Privacy Protection	Anonymization deep-dive
Privacy Quick Start	Privacy in 2 minutes
Error Recovery	Interactive error fixing
Troubleshooting	Common issues & solutions

Examples

Category	Guide
Python Errors	ModuleNotFoundError, ImportError, venv issues
Docker Errors	Build failures, port conflicts, volumes
Node.js Errors	npm, webpack, module resolution
Git Errors	Merge conflicts, auth, rebase

Comparisons

Comparison	What's compared
Privacy Libraries	detect-secrets vs presidio vs priv-masker vs datafog vs faker
Shell Error Fixers	heal vs thefuck vs shellcheck vs explainshell
LLM CLI Tools	heal vs aichat vs sgpt vs llm

Usage Examples

Python Development

# Missing dependencies
python app.py 2>&1 | heal
# → Suggests: pip install <missing-package>

# Import errors
python -m pytest 2>&1 | heal
# → Analyzes import paths and suggests fixes

# Virtual environment issues
python script.py 2>&1 | heal
# → Detects venv problems and suggests activation

Node.js / JavaScript

# NPM install failures
npm install 2>&1 | heal
# → Suggests clearing cache, fixing package.json, or using --legacy-peer-deps

# Build errors
npm run build 2>&1 | heal
# → Analyzes webpack/vite errors and suggests configuration fixes

# Module not found
node app.js 2>&1 | heal
# → Suggests installing missing packages or fixing import paths

Docker & Containers

# Docker build failures
docker build . 2>&1 | heal
# → Analyzes Dockerfile errors and suggests fixes

# Container runtime errors
docker-compose up 2>&1 | heal
# → Suggests port conflicts, volume issues, or network problems

# Permission issues
docker run myimage 2>&1 | heal
# → Suggests user/group fixes or volume mount corrections

Git Operations

# Merge conflicts
git merge feature-branch 2>&1 | heal
# → Suggests conflict resolution strategies

# Push/pull errors
git push origin main 2>&1 | heal
# → Analyzes authentication, branch tracking, or force push needs

# Rebase issues
git rebase main 2>&1 | heal
# → Suggests conflict resolution or rebase abort/continue

Build Systems

# Make errors
make build 2>&1 | heal
# → Analyzes missing dependencies or compilation errors

# CMake configuration
cmake . 2>&1 | heal
# → Suggests missing libraries or configuration flags

# Gradle/Maven builds
./gradlew build 2>&1 | heal
# → Analyzes Java compilation or dependency errors

Database Operations

# PostgreSQL connection
psql -U user -d database 2>&1 | heal
# → Suggests authentication fixes or connection string corrections

# MySQL import errors
mysql < dump.sql 2>&1 | heal
# → Analyzes syntax errors or permission issues

# MongoDB connection
mongosh mongodb://localhost:27017 2>&1 | heal
# → Suggests service status checks or authentication fixes

System Administration

# Permission denied
./script.sh 2>&1 | heal
# → Suggests chmod +x or sudo usage

# Port already in use
python -m http.server 8000 2>&1 | heal
# → Suggests finding and killing the process using the port

# Disk space issues
cp large-file.zip /destination 2>&1 | heal
# → Suggests cleaning up space or alternative locations

Package Management

# APT/DNF errors
sudo apt install package 2>&1 | heal
# → Suggests repository updates or alternative package names

# Homebrew issues
brew install tool 2>&1 | heal
# → Suggests tap additions or formula fixes

# pip install failures
pip install package 2>&1 | heal
# → Suggests using --user, venv, or resolving dependency conflicts

Commands

heal (default)

Fix shell errors using LLM. Reads from stdin or captured output.

heal [--model MODEL] [--api-key KEY]

heal init

Initialize bash integration for automatic command and output capture.

heal init

This will:

• Create ~/.heal/heal.bash with command capture hooks
• Optionally add to your ~/.bashrc automatically
• Enable helper commands: heal-last, heal-output

heal test

Test your configuration with a simulated error.

heal test

This will:

• Verify your provider and API key are configured
• Send a test request to the LLM
• Show you a sample response

heal config

Configure or reconfigure heal settings (provider, API key, model).

heal config

heal fix

Explicit fix command (same as default heal).

heal fix [--model MODEL] [--api-key KEY]

heal install

Legacy command (use heal init instead).

heal install

heal uninstall

Remove shell hook and configuration.

heal uninstall

heal --help

Show help message and available commands.

heal --help

Configuration

First-Time Setup

On first run, heal will guide you through an interactive setup:

$ heal

🔧 First-time setup - Let's configure your LLM provider

Available providers:
  1. OpenRouter (recommended)
  2. OpenAI
  3. Anthropic
  4. Google AI

💡 Tip: OpenRouter gives you access to all models with one API key

Select provider [1]: 1

🔑 Get your OpenRouter API key here:
   https://openrouter.ai/keys

Enter your API key: sk-or-...

🤖 Select a model from OpenRouter:

  1. openai/gpt-4o-mini
     GPT-4o Mini (fast, cheap, recommended)
  2. openai/gpt-4o
     GPT-4o (most capable)
  3. anthropic/claude-3.5-sonnet
     Claude 3.5 Sonnet (excellent reasoning)
  4. google/gemini-pro-1.5
     Gemini Pro 1.5 (long context)
  5. meta-llama/llama-3.1-70b-instruct
     Llama 3.1 70B (open source)
  6. qwen/qwen-2.5-72b-instruct
     Qwen 2.5 72B (multilingual)
  7. Custom (enter model name manually)

Select model [1]: 1

Reconfigure Settings

Change your provider, API key, or model anytime:

heal config

Supported Providers

🌐 OpenRouter (Recommended)

• Why? Access to all models with one API key
• Get API key: openrouter.ai/keys
• Models: GPT-4, Claude, Gemini, Llama, Qwen, and 100+ more

🤖 OpenAI

• Get API key: platform.openai.com/api-keys
• Models: GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-3.5-turbo

🧠 Anthropic

• Get API key: console.anthropic.com/settings/keys
• Models: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku

🔍 Google AI

• Get API key: aistudio.google.com/app/apikey
• Models: Gemini Pro, Gemini Pro Vision

Manual Configuration

Edit ~/.heal/.env:

HEAL_PROVIDER=openrouter
HEAL_API_KEY=your-api-key-here
HEAL_MODEL=openai/gpt-4o-mini
HEAL_BASE_URL=https://openrouter.ai/api/v1

Configuration is stored in ~/.heal/.env.

Testing

Unit tests

pip install -e ".[dev]"
python -m pytest -v

Privacy tests (57 test cases)

python -m pytest tests/test_privacy.py -v

Docker Testing

# All unit tests
docker compose run unit-tests

# Privacy tests only
docker compose run privacy-tests

# End-to-end CLI tests
docker compose run e2e-tests

# Full privacy suite with all backends
docker compose run privacy-full

Development

# Install in development mode
pip install -e ".[dev]"

# Run all tests
python -m pytest -v

# Run with coverage
python -m pytest --cov=heal -v

How it works

Command fails → heal captures output → anonymizes (optional) → LLM analyzes → suggests fix

1. Command capture — Gets last command from bash hook buffer or history
2. Error collection — Reads error output from stdin or captured file
3. Privacy masking — Optionally anonymizes sensitive data (6 backends)
4. LLM analysis — Sends sanitized command + error to LLM for analysis
5. Solution proposal — Returns concrete fix suggestions

Limitations

• Shell processes cannot access previous process stderr without pipes
• Shell hook required for fully automatic operation
• Requires API key for LLM service (free-tier models available)

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - [e-mail]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• PyPI: pypi.org/project/heal
• Changelog: CHANGELOG.md
• TODO: TODO.md
• Comparisons: comparisons/