Skip to content
BranchesTags

Repository files navigation

errex — Error Explainer

CI PyPI version Python versions

Paste or pipe any error message and get a clear, plain-English explanation powered by Claude — often without touching the API at all.

$ cat traceback.txt | errex

────────────────────── errex — Error Analysis ──────────────────────

⚡ matched local pattern

**TypeError: unsupported operand type(s) for +: 'int' and 'str'**

This is a Python type error. You're trying to add an integer and a
string together, which Python doesn't allow...

Install

pip install errex
export ANTHROPIC_API_KEY=sk-ant-...

Requires Python 3.9+. An Anthropic API key is needed for full explanations; local lookup commands work without one.

Quick start

errex                        # interactive paste
errex traceback.txt          # read from a file
cat error.log | errex        # pipe from stdin
errex --watch server.log     # tail a log, auto-explain errors

How it works

errex resolves every query through a three-tier speed hierarchy, from fastest to slowest:

  1. ⚡ Instant (local patterns) — 71 built-in patterns covering Python, JavaScript/Node.js, Rust, Java, Go, Docker, shell, Git, network, pip/npm. Matches happen in microseconds; no API call is made and no key is required. The response badge reads ⚡ matched local pattern.

  2. 📦 Fast (response cache) — When Claude has already answered the same error, the cached response is returned instantly from ~/.errex_response_cache.json (30-day TTL). The response badge reads 📦 cached response.

  3. 🤖 Full (Claude) — For anything new or complex, errex calls the Claude API and stores the result in the cache. Use --no-cache to skip tiers 1 and 2 and always call Claude directly.

Local lookup commands (no API key needed)

These commands return instant answers from built-in tables and never call Claude.

errex --explain-exit 139       # SIGSEGV — segmentation fault
errex --explain-http 429       # Too Many Requests — rate limited
errex --explain-cron "*/5 * * * *"  # "every 5 minutes"
errex --explain-env PYTHONPATH # what the variable controls
errex --list-patterns          # show all 71 built-in patterns in a table

All flags

Explaining errors

Flag What it does
errex [FILE] Explain an error from a file, stdin, or interactive paste
--brief One-paragraph summary instead of full analysis
--fix Output only the fix command, no explanation
--fix-apply Get a fix command from Claude and run it (prompts for confirmation)
--yes / -y Auto-confirm --fix-apply without prompting
--open-ticket Open a Red Hat Customer Portal support case with this error
--rht-username USER Red Hat username (or set RHT_USERNAME env var)
--rht-password PASS Red Hat password (or set RHT_PASSWORD env var)
--rht-severity 1-4 Ticket severity: 1=Urgent 2=High 3=Normal 4=Low (default: 3)
--rht-product NAME Red Hat product name for the ticket
--rht-version VER Product version for the ticket
--lang LANG Language hint when the error is ambiguous (e.g. rust, go, java)
--model MODEL Choose which Claude model to use (default: claude-sonnet-4-6)
--json Structured JSON output: error_type, root_cause, fix_steps, gotchas
--context FILE Attach a source file as extra context for more targeted explanations
--top N Limit root cause to top N most likely causes
--snippet Strip stdlib/library frames from a traceback before explaining
--format-json Reformat JSON error before explaining
errex A.txt B.txt Compare two error files and find shared root causes

Code tools

Flag What it does
--explain-code FILE Walk through what a piece of code does in plain English
--lint FILE Scan a code file for bugs, security issues, and anti-patterns
--test-gen FILE Generate a test case for a code file; pipe an error to reproduce the bug
--explain-diff [FILE] Explain a git diff — pipe git diff | errex --explain-diff or pass a .patch file
--explain-regex PATTERN Explain what a regex matches: breakdown, examples, gotchas
--explain-sql QUERY Explain a SQL query: clause breakdown, performance notes, gotchas
--explain-yaml FILE Explain a YAML config (auto-detects docker-compose, k8s, GitHub Actions)
--explain-dockerfile FILE Explain a Dockerfile layer by layer
--inline FILE LINE Explain a specific line of code in context
--grep PATTERN FILE Filter a log file by regex, then explain matching lines
--env Auto-attach system info (OS, Python, shell, runtimes) as context
--run CMD Run a shell command and auto-explain any error output
--redact Strip API keys, tokens, and passwords from error text before sending to Claude

Local lookups

Flag What it does
--explain-exit CODE Explain a shell exit code (e.g. 139 → SIGSEGV / segfault)
--explain-http CODE Explain an HTTP status code
--explain-cron EXPR Explain a cron expression in plain English
--explain-env VAR Explain what an environment variable controls
--list-patterns Show all 71 built-in patterns in a table

History & search

Flag What it does
--history [SEARCH] View past explanations, optionally filtered by keyword
--recent [N] Show the last N explanations (default: 5)
--since DATE Filter --history/--recent to entries on or after YYYY-MM-DD
--similar Find past errors in your history that match the current one
--search TERM Full-text search across all history fields
--interactive Browse history with a numbered picker
--dedup Show groups of near-duplicate errors in history
--ask "question" Ask a follow-up about the last error without re-explaining it
--retry Re-explain the last error with different flags (e.g. --retry --model claude-opus-4-7)
--stats Usage dashboard: total runs, models, top error types, busiest day/hour
--export FILE Export history to a styled HTML or Markdown file (--export-format html|md)
--export-csv FILE Export history to CSV (timestamp, model, error type, rating, name)
--save-as NAME Tag this explanation with a name for quick retrieval
--find-name NAME Retrieve a history entry saved with --save-as
--list-named List all history entries saved with --save-as
--add-note TEXT Append a note to the last history entry
--pin / --unpin Mark the last history entry as pinned (protected from --clear-history)
--filter TYPE Filter --history/--recent to entries matching an error type (e.g. TypeError)
--clear-history [DAYS] Delete all history, or only entries older than N days (pinned entries kept)
--rate SCORE Rate last explanation 1–5

Cache & performance

Flag What it does
--no-cache Skip the local pattern cache and response cache; always call Claude
--clear-cache Wipe the response cache (~/.errex_response_cache.json)
--tokens Show input/output token counts after each explanation
--perf Show response time and tokens/second after each explanation
--timeout N API request timeout in seconds (default: 30)

Workflow & integrations

Flag What it does
--watch LOGFILE Tail a log file and auto-explain new errors (deduplicates repeats)
--summarize-log FILE Digest all distinct error types in a large log file
--bulk FILE Explain multiple errors from a file separated by blank lines
--issues Search GitHub Issues for bugs matching your error
--share Post the explanation to paste.rs and print a shareable link
--copy Copy the explanation to the clipboard
--chat Stay in a Q&A loop after the explanation
--notify Send a desktop notification when the explanation is ready
--webhook URL POST explanation to a Slack, Discord, or generic webhook URL
--ci CI mode: no-color + terse output + GitHub Actions annotations + exits 1

Output & formatting

Flag What it does
--translate LANG Respond in a spoken language (--translate Spanish, --translate Japanese)
--json Structured JSON output: error_type, root_cause, fix_steps, gotchas
--terse Single-sentence diagnosis — shorter than --brief, great for scripting
--output FILE Save the explanation to a file alongside printing
--no-color Plain-text output with no rich formatting (safe to pipe)
--word-wrap N Set output console width
--copy Copy the explanation to the clipboard
--share Post the explanation to paste.rs and print a shareable link

System health scan

errex can scan your machine for security issues, misconfigurations, and outdated software — no API key needed for the scan itself.

errex --scan                 # run a full system scan
errex --scan --scan-network  # include network device scan
errex --scan-status          # show last scan result and health streak
Flag What it does
--scan Run a full system health scan (logs, configs, CVEs, malware)
--scan-schedule FREQ Schedule automatic scans (daily, weekly, monthly)
--scan-status Show last scan result and current health-streak days
--scan-network Also scan local network devices
--scan-severity LEVEL Only report findings at or above this severity (low, medium, high, critical)
--scan-fix Auto-apply safe fixes for scan findings
--scan-no-explain Skip Claude explanations; show findings only
--scan-quiet Suppress all scan output (useful in scripts; check exit code)
--scan-speak Read scan findings aloud via OS text-to-speech
--scan-malware [PATH] Run a malware/hash scan on PATH (default: home directory)
--check-hash FILE Check a file's SHA-256 hash against known-malware databases
--vt-api-key KEY VirusTotal API key for extended hash lookups
--simple Simplified, high-contrast output — fewer colours, larger text; good for accessibility
--mascot Show Rex (errex's mascot) with a context-aware motivational line

Scan tickets

Scan findings are tracked as tickets so nothing gets lost between sessions.

Flag What it does
--tickets List all open scan tickets
--ticket-close ID Mark a ticket as resolved
--ticket-snooze ID Snooze a ticket (default: 7 days; override with --snooze-days N)
--snooze-days N Number of days to snooze (used with --ticket-snooze)
--ticket-reopen ID Reopen a previously closed/snoozed ticket
--ticket-note ID --note TEXT Append a note to a ticket

Network devices

errex remembers the devices on your local network and lets you give them friendly names.

Flag What it does
--devices List all known network devices with their nicknames
--device-rename IP --name NICK Set a friendly nickname for a device (e.g. --device-rename 10.0.0.5 --name "Living Room TV")

Backup & restore

Before applying any auto-fix, errex backs up the affected files so you can always roll back.

errex --backups               # see all auto-fix backups
errex --restore-backup PATH   # restore a specific backup
errex --cloud-backup          # copy backups to a detected cloud-sync folder
errex --restore-point         # create an OS restore point before a big fix
Flag What it does
--backups List all auto-fix backups (newest first)
--restore-backup PATH Restore a file from its backup (PATH is the backup file path shown by --backups)
--cloud-backup Copy the backup folder into a detected cloud-sync folder (Dropbox, Google Drive, OneDrive, iCloud)
--restore-point Create an OS-level restore point before fixing: Time Machine snapshot (macOS), System Restore (Windows), or timeshift (Linux)

Weekly digest & notifications

Flag What it does
--digest Print a summary of errors and fixes from the last 7 days
--digest-since N Override the look-back window to the last N hours
--discord-webhook URL Post the explanation or scan summary to a Discord channel
--github-token TOKEN GitHub token for --issues lookups and PR annotations
--github-repo OWNER/REPO GitHub repo to open issues against

Cloud sync

Flag What it does
--sync-url URL Remote endpoint to sync scan summaries and ticket events
--sync-key KEY API key for the sync endpoint (or set ERREX_SYNC_KEY env var)

PR review

errex --review-pr https://github.com/owner/repo/pull/42
errex --review-pr owner/repo#42   # shorthand
Flag What it does
--review-pr URL Fetch a GitHub PR diff and get a structured Claude code review (summary, issues, suggestions, verdict)

Slack notifications

Flag What it does
--slack-webhook URL Slack incoming webhook URL for scan summaries and ticket events (or set ERREX_SLACK_WEBHOOK)

Jira integration

errex --scan --jira-project SEC --jira-url https://myteam.atlassian.net \
      --jira-user me@co.com --jira-token $JIRA_TOKEN
Flag What it does
--jira-project KEY Jira project key — creates issues for each new scan finding
--jira-url URL Jira instance base URL
--jira-user EMAIL Jira username / email
--jira-token TOKEN Jira API token (prefer env var JIRA_TOKEN)

Prometheus metrics

errex --prometheus 9100   # exposes http://localhost:9100/metrics
Flag What it does
--prometheus PORT Start a metrics server exposing error counts, open tickets by severity, and health streak in Prometheus text format

Project config

errex --init-project          # creates .errex.yml in current directory
errex --init-project --force  # overwrite existing

Commit .errex.yml to share settings (model, scanner options, ignored findings) across your team.

Flag What it does
--init-project Create a .errex.yml project config in the current directory
--force Overwrite existing file (used with --init-project)

Auto-scan daemon

errex --auto-scan 60                                    # scan every 60 minutes
errex --auto-scan 30 --slack-webhook $SLACK_URL         # alert on new findings
errex --auto-scan 60 --scan-severity medium             # medium+ only
Flag What it does
--auto-scan MINUTES Run scans on an interval; alert only when findings change (new or resolved)

AI fix suggestions

errex --suggest-fixes
errex --suggest-fixes --scan-severity high
Flag What it does
--suggest-fixes Scan the system and ask Claude for concrete shell commands to fix each finding

Pro license

errex --activate ERREX-PRO-XXXXXX-XXXXXXXX   # activate a Pro license key
errex --license                               # show current license status
Flag What it does
--activate KEY Activate an errex Pro license key
--license Show current license status (free / Pro, expiry, seat)

Setup & config

Flag What it does
--config [key=value] View or edit ~/.errexrc — e.g. --config model=claude-opus-4-7
--profile NAME Use a named config profile
--list-profiles List all named profiles in ~/.errexrc
--delete-profile NAME Delete a named profile from ~/.errexrc
--setup First-run wizard: check API key, detect languages, write config, install shell integration
--doctor Health check: verify API key, connectivity, config, and version
--completion bash|zsh Print a shell completion script (source <(errex --completion zsh))
--install-shell Add errex-last() to your shell — run it after any failed command
--web Launch a local web UI at http://localhost:7337
--update Check PyPI for a newer version
--version Show the installed version

Web UI

errex --web   # opens http://localhost:7337

The web UI provides a browser-based interface with:

  • Real-time token streaming — explanation text appears as Claude generates it
  • History sidebar — past explanations listed on the left; click any entry to reload it
  • Source badge — shows whether the result came from ⚡ a local pattern or 🤖 Claude
  • Full / Brief mode tabs — toggle between detailed and summary views
  • Copy button and Cmd/Ctrl+Enter keyboard shortcut

Config file

~/.errexrc sets your defaults (all fields optional):

{
  "model": "claude-opus-4-7",
  "brief": false,
  "lang": "python",
  "copy": false
}

Or manage it from the CLI:

errex --config                        # show all settings
errex --config model=claude-opus-4-7  # set a value
errex --config lang=null              # reset to default

Named profiles let you keep separate configs for different projects:

errex --profile work                  # activate the "work" profile
errex --list-profiles                 # list all profiles
errex --delete-profile work           # remove a profile

Shell integration

errex --install-shell   # adds errex-last() to ~/.zshrc or ~/.bashrc

After any failed command, run errex-last to explain why it failed.

History

Every explanation is saved to ~/.errex_history (one JSON object per line).

errex --recent              # last 5 explanations
errex --history KeyError    # search history
errex --search "import"     # full-text search across all fields
errex --interactive         # browse with a numbered picker
errex --dedup               # show groups of near-duplicate errors
errex --stats               # usage dashboard
errex --export report.html  # export to HTML
errex --rate 5              # rate the last explanation 1–5

CI/CD integration

Use --ci for pipeline-friendly output:

cat build.log | errex --ci

--ci mode enables:

  • No-color, terse output safe for log capture
  • GitHub Actions error annotations (::error::) printed to stdout
  • Exit code 1 so the step fails visibly

Example GitHub Actions step:

- name: Explain build failure
  if: failure()
  run: cat build.log | errex --ci

Deployment

Docker (quickstart)

docker run -e ANTHROPIC_API_KEY=sk-... -p 7337:7337 ghcr.io/bsel153/errex:latest

Or with docker-compose:

export ANTHROPIC_API_KEY=sk-...
docker-compose up -d

Open http://localhost:7337 in your browser. All history, cache, and config are stored in the errex-data Docker volume.

With authentication and TLS (recommended for public-facing deployments):

# docker-compose.yml
command: ["--auth", "admin:changeme", "--tls"]

systemd (Linux server)

# 1. Create a dedicated user
sudo useradd -r -m -d /var/lib/errex errex

# 2. Install errex
sudo pip install errex

# 3. Install the service file
sudo cp deploy/errex.service /etc/systemd/system/errex.service

# 4. Set your API key
sudo systemctl edit errex
# Add under [Service]:
#   Environment=ANTHROPIC_API_KEY=sk-...

# 5. Enable and start
sudo systemctl daemon-reload
sudo systemctl enable --now errex

# 6. (Optional) Add nginx reverse proxy
sudo cp deploy/nginx.conf /etc/nginx/sites-available/errex
sudo ln -s /etc/nginx/sites-available/errex /etc/nginx/sites-enabled/
sudo certbot --nginx -d errex.yourdomain.com
sudo systemctl reload nginx

The service listens on 127.0.0.1:7337 by default and is proxied through nginx with HTTPS.

LAN / mobile access

errex --web --host 0.0.0.0 --port 7337

Access from any device on your local network at http://<your-ip>:7337.

For temporary public internet access with a shareable link and QR code:

errex --web --tunnel

What you get

For any error, errex explains:

  1. What kind of error it is and which language or tool produced it
  2. What it means in plain English
  3. The most likely root cause, ranked by probability
  4. Numbered fix steps with code snippets where helpful
  5. Common gotchas — the non-obvious things that trip people up

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages