heal

Heal 🩺

LLM-powered shell error fixing - Your AI assistant for debugging and fixing command-line errors instantly.

Installation

pip install heal

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 - Anonymize sensitive data before sending to LLM (optional)
• 🚀 Zero-config start - Just run heal after any error

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.

Development

This package uses modern Python packaging with pyproject.toml.

Install in development mode

pip install -e .

Run tests

python -m pytest

How it works

1. Command capture: Gets last command from bash history or shell hook
2. Error collection: Reads error output from stdin or captured file
3. LLM analysis: Sends command and error to LLM for analysis
4. 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

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - tom@sapletta.com

Contributing

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

This site is open source. Improve this page.