Inspiration
An app works perfectly—until the next update. Suddenly, tests fail, imports break, or familiar features behave differently. Finding the cause often means digging through logs and commits, trying to work out what changed.
CausalTrace grew out of that frustration. AI can suggest what went wrong, but developers still need evidence: where the failure started, whether a particular change caused it, and whether the suggested repair holds up.
What it does
CausalTrace helps developers investigate bugs introduced by software updates.
It runs tests in isolated Docker containers and works backward through Git history to find a passing-to-failing transition. It then reverses suspected changes to check whether removing them resolves the failure. An unrelated commit can serve as a control, helping distinguish a likely cause from a coincidence.
NVIDIA Nemotron, running through Nebius Token Factory, examines selected code, logs, and diffs to explain the problem and suggest repairs. Proposed changes are checked against unchanged tests before being described as verified.
The original repository stays untouched, and developers can download an evidence report to review the findings.
How it was built
CausalTrace combines a Python and FastAPI backend with a React and TypeScript dashboard. Git supplies the revision history, and Docker provides isolated environments for running tests and trying repairs.
Nebius Token Factory connects the application to NVIDIA Nemotron for diagnosis and code suggestions. The model proposes changes, while separate validation checks decide whether those changes are allowed and whether they improve the test results.
Compatible runners support Python, JavaScript/TypeScript, Java, and Go. GitHub Actions checks the backend, frontend, Docker workflows, and test-build packaging.
Challenges along the way
One of the hardest problems was deciding what a test result actually means. A missing dependency, skipped test, or broken environment should never be presented as proof that a commit passed or failed.
Protecting local work was equally important. Investigations use independent snapshots so experiments do not interfere with the developer’s original files.
AI suggestions brought another challenge. During a live rehearsal, Nemotron suggested changing a test instead of restoring the expected behavior. CausalTrace rejected the proposal. That moment reinforced an important design decision: the model can suggest a repair, but it cannot decide that its own repair is correct.
Accomplishments worth highlighting
CausalTrace brings several difficult debugging steps into one workflow: reproducing a failure, examining history, testing a suspected cause, and evaluating a proposed repair.
The most meaningful achievement is keeping those results separate and understandable. An AI explanation is labeled as a suggestion. A reversal has its own measured outcome. A repair is verified only when the unchanged tests pass.
Built as a solo project, CausalTrace also includes multilingual test runners, accessible controls, downloadable evidence, and pause, resume, and stop support for investigations.
What the project taught
Good debugging starts with a reproducible problem. Without that foundation, even a detailed explanation can send a developer in the wrong direction.
Building CausalTrace showed how much care is needed around AI-generated code. A plausible change can still be wrong, and passing tests only establish the behavior those tests cover.
It also showed the value of an honest inconclusive result. When an environment cannot run a historical suite or the available tests do not reproduce a defect, saying so gives developers a clearer starting point than an unsupported claim.
What's next for CausalTrace
The next step is making investigations work across more realistic application environments, including projects with service dependencies and framework-specific setup.
Other priorities include more reproducible historical environments, clearer progress updates, and stronger repair evaluation. Longer term, authenticated team workflows could make it easier to review proposed patches within existing development tools.
The goal remains practical: spend less time guessing which update broke the app, and give developers a clearer path from a failure to a tested repair.
Log in or sign up for Devpost to join the conversation.