What TraceCI is
TraceCI is an agent that reads a failed GitHub Actions run and traces the failure back to the change that caused it, with the log lines and source that prove it.
- GitHub Actions
- read-only
- bring your own key
- ≤ 6 tool calls
- ~15s
The problem it solves
A red build tells you a step exited non-zero. It does not tell you which of the fourteen commits since the last green run is responsible, whether the traceback is pointing at the bug or at a victim of the bug, or whether the failure has anything to do with your change at all. Working that out means opening the run, scrolling several thousand lines of installation output to find the first real error, going back to the commit list to work out what the last passing run was, and then reading source to check whether what the log claims is actually true.
That sequence is mechanical up to the last step, and the last step is where judgement is needed. TraceCI automates the mechanical part exactly, and applies a model only where a decision has to be made.
What it does
Given a repository, TraceCI:
- Finds the most recent failed workflow run, on a branch if you name one.
- Identifies the first step that actually failed, and builds a log window anchored on the first real error rather than on the end of the file.
- Resolves the last green commit on that branch and diffs it against the failing one, so the comparison is the one that matters.
- Hands all of that to an agent that decides for itself whether it needs to open source files, read a specific patch, search for a symbol, or read more of the log.
- Returns a typed result: a category, a root cause naming file and function, two to five verbatim evidence lines, a confidence score, a suggested fix and often a minimal patch.
Steps one to three involve no model at all. They are the same every time, so letting something choose whether to do them would only add latency and a new way to fail.
What it is not
| Not this | Because |
|---|---|
| A chatbot | There is no conversation. One failed run in, one structured diagnosis out. The prose you see streaming is the agent working, not a reply to you. |
| An autofixer | TraceCI has no write access to anything. It suggests a patch; applying it is your decision and your commit. |
| A log search tool | Grep finds the error line. The error line is usually not the cause — that is the entire difficulty. |
| A CI provider | It reads runs that GitHub Actions already produced. It does not schedule, run or re-run anything. |
What it guarantees
- Read-only. No commits, comments, pull requests, re-runs or pushes exist anywhere in the system. The worst outcome of a wrong diagnosis is a paragraph of text.
- Pinned reads. Every file the agent opens is read at the exact commit that failed. Reading
mainwhile diagnosing a branch produces a diagnosis that contradicts its own evidence. - Bounded work. Six tool calls per investigation, enforced in code, with a graph recursion limit behind it as a backstop.
- Your key, once. The key you supply is used for one request and is never written to graph state, checkpoint metadata or a shared record.
Where to start
If you have a repository with a red build and an API key, go straight to the quickstart. If you would rather see a finished result first, replay a recorded investigation — it is a captured live run, replayed through the same interface, and needs no key.