semcod

← all projects

heal

A Python package for healing and wellness

Python updated 3w ago View on GitHub → Homepage

Heal 🩺

PyPI version
Python versions
License: Apache-2.0
Tests
Docker
Privacy

AI Cost Tracking

PyPI Version Python License
AI Cost Human Time Model

  • 🤖 LLM usage: $68.9556 (34 commits)
  • 👤 Human dev: ~$1390 (13.9h @ $100/h, 30min dedup)

Generated on 2026-07-07 using openrouter/qwen/qwen3-coder-next

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]

5. Use heal - just run any command and then heal!

python broken_script.py
heal


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

# With privacy protection (anonymize sensitive data)
production_script.py 2>&1 | heal -a
# or long form:
production_script.py 2>&1 | heal --anonymize

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:

```bash
# Anonymize secrets, PII, tokens before sending to LLM
production_script.py 2>&1 | heal --anonymize
# or use the short flag:
production_script.py 2>&1 | heal -a

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

### Privacy Flags

| Flag | Description |
|------|-------------|
| `-a`, `--anonymize` | Force anonymization (overrides default) |
| `--no-anonymize` | Disable anonymization (overrides default) |
| `--privacy-check` | Show available privacy backends |

### Default Behavior

During first configuration (`heal config`), you'll be asked whether to enable anonymization by default. This setting can be overridden with flags:

```bash
# Disables anonymization regardless of default  
heal fix --no-anonymize
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

Missing dependencies

python app.py 2>&1 | heal

Import errors

python -m pytest 2>&1 | heal

Virtual environment issues

python script.py 2>&1 | heal

NPM install failures

npm install 2>&1 | heal

Build errors

npm run build 2>&1 | heal

Module not found

node app.js 2>&1 | heal

Docker build failures

docker build . 2>&1 | heal

Container runtime errors

docker-compose up 2>&1 | heal

Permission issues

docker run myimage 2>&1 | heal

Merge conflicts

git merge feature-branch 2>&1 | heal

Push/pull errors

git push origin main 2>&1 | heal

Rebase issues

git rebase main 2>&1 | heal

Make errors

make build 2>&1 | heal

Gradle/Maven builds

./gradlew build 2>&1 | heal

PostgreSQL connection

psql -U user -d database 2>&1 | heal

MySQL import errors

mysql < dump.sql 2>&1 | heal

MongoDB connection

mongosh mongodb://localhost:27017 2>&1 | heal

Permission denied

./script.sh 2>&1 | heal

Port already in use

python -m http.server 8000 2>&1 | heal

Disk space issues

cp large-file.zip /destination 2>&1 | heal

APT/DNF errors

sudo apt install package 2>&1 | heal

Homebrew issues

brew install tool 2>&1 | heal

pip install failures

pip install package 2>&1 | heal

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

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-5.4-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

🌐 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

🧠 Anthropic

🔍 Google AI

Manual Configuration

Edit ~/.heal/.env:

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

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

Unit tests

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

Privacy tests (57 test cases)

python -m pytest tests/test_privacy.py -v

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


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

# 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

Licensed under Apache-2.0.

Author

Tom Sapletta

Contributing

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

Links

<!-- taskill:status:start -->

Status

Last updated by taskill at 2026-04-25 13:38 UTC

Metric Value
HEAD 72de64a
Coverage —
Failing tests —
Commits in last cycle 26

Work focused on CLI-related documentation and interface polish, plus a broad refactor of the configuration and test modules. Additional chores introduce a deep code analysis engine and example/configuration improvements.

<!-- taskill:status:end -->