DEV Community: ci why

Why does my CI keep failing? (and how to stop guessing)

ci why — Thu, 30 Apr 2026 13:08:14 +0000

Every developer knows this moment.

You push a commit. CI runs. It fails. You open the log and stare at 400 lines of output trying to find the one line that actually matters.

Ten minutes later you're still scrolling.

Why CI logs are so hard to read

CI runners don't write logs for humans. They write them for machines. Everything gets dumped — timestamps, progress bars, ANSI escape codes, dependency install output, test runner boilerplate — and somewhere buried in all of it is the actual error.

The problem isn't that CI is broken. The problem is that the signal is buried under noise.

The most common reasons CI fails

1. A test is failing
Someone changed code that broke an existing test, or a mock is returning the wrong value. The error is in there — you just have to find it.

2. A dependency version conflict
Your CI runner is on a different version of Node, Python, or another runtime than your local machine. Works on your laptop, fails in CI.

3. An environment variable is missing
A secret or config value exists in your local .env but wasn't added to your CI secrets. The app crashes on startup.

4. A timeout
A test or build step is taking too long and CI kills it. The log just says "Process killed" with no explanation.

5. A flaky test
A test that passes 95% of the time but fails randomly due to timing, network, or order-of-execution issues.

The slow way vs the fast way

The slow way is what most developers do — scroll the raw log, Ctrl+F for "error", guess what went wrong, push a fix, wait for CI to run again, repeat.

The fast way is to pipe your log through ci-why:

cat build.log | ci-why

It strips all the noise, sends the relevant parts to Claude, and prints back a plain English explanation:

──────────────────────────────────────────────────
  WHY
  The authentication service returns null for the token field
  instead of a valid string, causing the test assertion to fail.

  FAILING LINE
  src/services/auth.test.ts:63

  SUGGESTED FIX
  Check authService.login() in auth.ts — it's returning
  {"token": null} for valid credentials.
──────────────────────────────────────────────────

Instead of reading 300 lines, you read 8.

How to set it up

npm install -g ci-why
ci-why setup

The setup wizard walks you through getting a free Anthropic API key and saves it automatically. Takes about 2 minutes.

Then any time a build fails:

# Pipe directly
cat build.log | ci-why

# Or point at a file
ci-why ./logs/build.log

# Get JSON output for scripting
ci-why --json ./build.log

It works with Jest, pytest, Go test, Rust/Cargo, and Maven — auto-detected from your log.

Works in GitHub Actions too

Add it to your workflow and it automatically posts a plain English explanation as a PR comment every time a build fails:

- name: Explain failure with ci-why
  if: steps.build.outcome == 'failure'
  uses: ciwhy-tool/ci-why@v0.2.0
  with:
    log-file: /tmp/build.log
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    github-token: ${{ secrets.GITHUB_TOKEN }}
    pr-number: ${{ github.event.pull_request.number }}

Every developer on your team sees the explanation — not just the one who installed the tool.

Free and open source

ci-why is completely free. You bring your own Anthropic API key (free to get, costs fractions of a cent per run).

npm install -g ci-why

GitHub: github.com/ciwhy-tool/ci-why

Tags: devops, node, testing, productivity, opensource

I built a CLI that reads your broken CI log and tells you why it failed in plain English

ci why — Thu, 30 Apr 2026 12:05:06 +0000

Every developer knows the feeling.

Your CI pipeline fails. You open the log. There are 300 lines of noise — progress bars, timestamps, test runner output — and somewhere buried in there is the one line that actually matters.

I got tired of hunting for it. So I built ci-why.

What it does

You pipe your failed CI log into it, and it tells you:

WHY the build failed (in one sentence)
Which exact line caused it
What to fix

cat build.log | ci-why

That's it. You get back something like this:

──────────────────────────────────────────────────
  WHY
  The authentication service is returning null for the token field
  instead of a valid token string, causing the test assertion to fail.

  FAILING LINE
  src/services/auth.test.ts:63

  SUGGESTED FIX
  Check authService.login() in auth.ts — it's returning {"token": null}
  for valid credentials. The login logic needs fixing, not the test.
──────────────────────────────────────────────────

Instead of reading 300 lines, you read 8.

How to install it

npm install -g ci-why

You'll need an Anthropic API key (free to get at console.anthropic.com). Set it once:

export ANTHROPIC_API_KEY=your-key-here

Then use it however fits your workflow:

# Pipe from anywhere
cat build.log | ci-why

# Point at a file
ci-why ./logs/build.log

How it works

ci-why does four things under the hood:

Strips the noise — removes ANSI escape codes, progress bars, timestamps, and anything else that clutters CI logs
Finds the signal — pulls out lines containing errors, exceptions, and failures, plus the last section of the log
Asks Claude — sends the cleaned excerpt to the Anthropic API with a tight prompt asking for: why, where, and how to fix it
Prints the result — formats it into the clean coloured output you saw above

The whole thing uses claude-haiku which is fast and cheap. A typical analysis costs less than a fraction of a cent.

It's free and open source

ci-why is completely free. You bring your own Anthropic API key so there's no subscription, no account, no billing through me.

The code is on GitHub: github.com/ciwhy-tool/ci-why

A paid cloud tier with GitHub Actions integration and team features is planned for the future — but the core CLI will always be free and open source.

What's coming next

GitHub Actions integration (auto-comment on PRs with the failure explanation)
Support for more log formats (pytest, Go test, Cargo, Maven)
--json flag for piping output into other tools

Try it and let me know what you think

If you try ci-why and hit a bug, have a suggestion, or just want to say it helped — drop a comment below or open an issue on GitHub. This is v0.1 and real feedback from real developers is exactly what I need to make it better.

npm install -g ci-why

Update: v0.1.2 is out — better error messages, --version and --help flags, and graceful handling of empty logs. npm install -g ci-why to get it.