Chronos

Chronos analyzes your repo's real git history and dependency graph to forecast architecture risk 12 months out, then uses Codex to generate the preventative refactor — before the problem exists.

Comment

Inspiration

Every AI coding tool today is reactive: linters flag what's wrong now, copilots help you write the next line now. Nothing looks at where a codebase is actually headed. Technical debt is not random — it's a compounding, predictable process driven by measurable signals (churn, coupling, complexity, ownership concentration) that show up in git history long before they show up as an incident. We wanted to build the tool that reads those signals the way a good staff engineer does, except automatically, continuously, and for every module in a repo — and then closes the loop by generating the actual fix.

What it does

Chronos imports a repository and:

  1. Computes real signals from git history — module-level churn, cross-module coupling (via AST import analysis), cyclomatic complexity (Radon), and contributor concentration/bus factor (PyDriller) — sampled at multiple historical checkpoints, not just the current snapshot.
  2. Projects those trendlines forward to 6 and 12 months, producing a composite health score and a per-module risk score.
  3. Visualizes the forecast on an interactive timeline: drag through Today → 6mo → 12mo and watch the dependency graph, health score, and bug-hotspot heatmap update live.
  4. Explains every prediction in plain language via Architecture Doctor, a GPT-5.6-powered explanation that is constrained to the actual computed signals — it can cite churn/coupling/complexity numbers, but it cannot invent a claim that isn't backed by real analysis.
  5. Lets you preview a fix ("Butterfly Effect") and see the projected before/after impact on health score and critical-module count.
  6. Generates a real preventative patch — "Prevent This Future" sends the flagged module's actual source code and its computed risk signals to Codex, which returns a diff, PR description, and test list. The diff is validated with git apply --check before it's ever shown, and the endpoint fails cleanly and honestly rather than fabricating a result if a model call is unavailable.

How we built it

  • Backend: FastAPI + Python. Git analysis via GitPython/PyDriller, complexity via Radon, coupling via a custom AST import-graph walker. All of it computes historical checkpoints (not just current state) so the forecast is a real extrapolation of an actual trendline, not a guess.
  • Frontend: a single-page dashboard built to a dark, glassmorphic design system — interactive timeline, a dependency graph that stays legible from 15 to 50+ modules, live health scoring, and a diff viewer for generated patches.
  • Single-origin deployment: the frontend is served directly by FastAPI (StaticFiles mount) so the whole demo runs as one process on one origin — no CORS, nothing to misconfigure live.
  • Caching architecture: every forecast and every generated patch is cache-first, keyed by repo + module, so the demo experience is sub-200ms even though the underlying analysis (a full git history walk across thousands of commits, for large repos) can take minutes. This was a deliberate reliability decision after we measured just how expensive full-history analysis actually is.

How GPT-5.6 was used

Architecture Doctor's explanations are generated by GPT-5.6, but deliberately not as free-form chat — the model receives a structured payload of already-computed numbers (churn rate, coupling edge count, complexity score, contributor count) and is constrained to explain those specific values causally, not to invent its own risk assessment. Every claim Architecture Doctor makes is traceable back to a real, computed number.

How Codex was used

Codex powers "Prevent This Future": given a flagged module's real source file and its computed risk signals, Codex proposes a scoped, single-file refactor as a unified diff, a PR description, and a list of tests to add. We validate every returned diff with git apply --check against the real repository before accepting it, retry once on a malformed response, and fail with a clear error state rather than fabricate a patch if generation isn't possible.

Codex was also our primary build tool throughout development: Codex scaffolded the FastAPI backend and the full analysis pipeline (git history walking via PyDriller, AST-based import coupling graph, Radon complexity scoring), iterated on the pipeline against six real repositories to validate it against genuine data rather than assumptions, and found and fixed a real bug in our own risk-scoring formula — a saturation issue where churn, coupling, and complexity were independently capped before weighting, pinning one module's score at 95% across all three forecast checkpoints regardless of how much its underlying signals actually grew. Codex traced that bug to its root cause, rebalanced the formula, and re-validated it against every previously-tested repository to confirm nothing regressed. It also built the entire frontend dashboard (the interactive timeline, the dependency graph with collision-safe layout at both small and 50+ module scale, the diff viewer), diagnosed and fixed a stale-state bug where switching repositories without a page refresh left leftover UI state from the previous repo, and implemented the cache-first architecture for both the forecast and patch-generation endpoints so the live demo never depends on a slow or rate-limited external API call succeeding on stage.

Challenges we ran into

  • Finding a real repository with a genuinely declining health trajectory. We tested six real repos — itsdangerous, Click, Requests, Gunicorn, Jinja2, and one of our own projects — and every single one came back flat. That turned out to be an important, honest finding: actively-maintained software doesn't decay, because being popular is what keeps it maintained. We ultimately built a small constructed teaching repository with real, backdated git history and a deliberately realistic debt-accumulation pattern in one module, clearly labeled as an illustrative example, to demonstrate the forecasting pipeline against a genuine decline.
  • A risk-scoring bug that saturated early. Our first composite risk formula capped churn, coupling, and complexity independently before weighting them, which meant a single already-maxed signal could pin the whole score near 100% regardless of how much worse things got afterward. We found this by watching a real module's risk score stay flat at 95% across all three timeline checkpoints despite its underlying signals clearly climbing. We rebalanced the formula with smoother bounded curves, verified it didn't regress any of our six previously-tested real repos, and added a regression test to lock in the fix.
  • API reliability for live model calls. We built cache-first serving for both endpoints specifically so the demo never depends on a live external API call succeeding under conference wifi — every result shown live is either instant from a validated cache, or the user can explicitly opt into a live call to watch it happen.

Accomplishments that we're proud of

  • A forecast that is fully traceable: every risk score and every AI explanation can be traced back to real, computed git/complexity/coupling numbers — nothing is a black-box guess.
  • The honesty of the system: when a repo's forecast is flat, Chronos says so, rather than manufacturing drama to make a better demo.
  • A fully working end-to-end loop from "here's a repo" to "here's a validated, real code diff that prevents the predicted problem" — not a mockup of that loop, an actual one.

What we learned

Traceability mattered more than model sophistication. The moment we constrained GPT-5.6's explanations to only cite numbers our own pipeline had already computed — rather than letting it reason freely — the whole product became something we could stand behind under questioning, instead of a plausible-sounding black box. We also learned this the hard way on the data side: we assumed real-world software would readily show architectural decline, and it mostly doesn't. Six well-maintained repositories all came back flat, because popularity is what keeps a codebase maintained. That pushed us to be explicit about what "flat" means (a system correctly recognizing stability, not failing to find drama) and to build one small, clearly-labeled constructed example specifically to demonstrate a genuine decline — rather than force our own numbers to look worse than they honestly were.

What's next for Chronos

  • Parallel "future" branches (multiple simulated architectural paths, not just one linear projection)
  • Live GitHub repo import (currently local path/zip only)
  • Natural-language querying of the forecast ("what breaks first if we add 5 developers?")
  • Streaming/incremental analysis so large monorepos don't require a full multi-minute history walk

Built With

Share this project:

Updates