Command

`okulo trend`

Track code health over time for hotspots or specific files — is it getting worse?

healthhistory

When to use it

You have candidate hotspots and want to know whether mess is rising or long-standing.

Usage

okulo trend [repo] [options]

Options

Option	Default	Description
`--file PATH`	top hotspots	File to analyze (repeatable)
`--samples`	8	Revisions sampled per file across history
`-n, --limit`	20	How many hotspot files when --file is omitted
`-w, --window`	12m	Still used for hotspot selection defaults

Examples

Trends for the worst hotspots

okulo trend -n 5

Deep dive on one file

okulo trend --file src/billing/invoice.py --samples 12 -w all

Compare two related modules

okulo trend --file web/checkout/Cart.tsx --file web/checkout/Pay.tsx

Sample output

Illustrative terminal output (column layout matches the real CLI):

Code health trend  sampled across each file's revisions in the window
file                     status      start   end    Δ  trend  Δ loc  Δ cognitive
───────────────────────  ─────────  ─────  ────  ───  ─────  ─────  ───────────
src/billing/invoice.py   declining    6.4   3.1  -3.3  ▂▁     +38%       +55%
web/checkout/Cart.tsx    declining    6.9   4.8  -2.1  ▃▂     +22%       +31%
lib/auth/session.ts      stable       7.5   7.4  -0.1  ██      +4%        +2%

How to read it

start → end / Δ — health at the first vs last sample. Δ ≤ −0.5 is typically marked declining.
Δ loc / Δ cognitive — the file is growing and/or getting branchier, which often explains the decline.
Prefer refactoring declining hotspots over files that have always been messy but stable.

Tips

A declining trend on a hotspot is a stronger refactor signal than a static low health score alone.

okulo trend