ci-whisper

Read a failed CI log. Get the first real error, its causal chain, and a fix. One paragraph instead of ten thousand lines of noise.

Install

pipx install git+https://github.com/mgkvibez/ci-whisper.git

Until it is on PyPI, install from git. For development: git clone && pip install -e ".[dev]".

Three ways to use it

# 1. The one you will use daily: pipe the failing job log
gh run view --log-failed | ci-whisper

# 2. From a downloaded log file
ci-whisper --file /tmp/build.log

# 3. Let it fetch the last failed run of the current repo
ci-whisper --gh 16977481234

# machine-readable, for a bot or an agent skill
ci-whisper --file build.log --json

Exit code is 1 when no error signal is found, so you can gate on it.

Why it exists

A red build hands you 10k lines. The actual cause is line 4, and everything after it is consequence: retries, cascading test failures, the polite ##[error]Process completed with exit code 1.

Two things go wrong when this hits an agent. It reads the last error and fixes a symptom, or it reads the header and summarises nothing. ci-whisper ranks signals so the cause outranks its own consequences, then shows the citations so anyone can check the call.

How it works

1. Clean — strips ANSI and GitHub's 2026-10-29T08:01:02.1234567Z timestamp prefix, keeping a line-number map to the original file.
2. Scan — matches a ranked rule set: ModuleNotFoundError/Exception (4) beat Traceback, test failures and compiler errors (3), which beat npm ERR! and ##[error] (2), which beat a bare exit code 1 (1).
3. Root cause — highest severity, then earliest line. Noise (warnings, deprecations, 0 failed, download progress) is filtered before ranking.
4. Chain — the chosen line plus the following block: indented continuations, frames, and caused by style links.
5. Fix — a rule per failure shape: peer dependency conflict, missing module, permissions, missing path, assertion, timeout, OOM.

No network calls, no LLM, no dependencies.

Contributing

Read CONTRIBUTING.md. Tests:

python -m pytest -q

License

MIT. See LICENSE.