Getting started

Install Okulo, point it at a Git repo with real history, and run a short analysis loop.

Requirements

• Git on your PATH.
• A Git repository with history. Shallow clones (--depth 1) have almost nothing to analyze — run git fetch --unshallow if needed.

The distributed binary has no Python dependency. (Building from source needs Python ≥ 3.11.)

Install

macOS / Linux:

curl -fsSL https://getokulo.dev/install.sh | sh
okulo --version

Windows (PowerShell):

irm https://getokulo.dev/install.ps1 | iex

Optional: OKULO_VERSION=0.1.0, OKULO_INSTALL_DIR=~/.local/bin.

Five-minute tour

Run these from inside your repo (or pass a path: okulo hotspots ~/code/my-repo).

1. What history did Okulo read?

okulo log

Commits, authors, and files in the analysis window (default 12 months).

2. Where is the hot code?

okulo hotspots

Ranks files by change frequency × complexity. Rows marked ● are hotspots — usually a small slice of the codebase absorbs most change.

3. What is it costing?

okulo debt --hourly-rate 50 --currency EUR

Separates active debt (still collecting interest) from inactive debt, with estimated hours lost.

4. What should we refactor?

okulo refactor --top 3

Function-level recommendations for the most expensive files.

5. Are we one resignation away from trouble?

okulo busfactor

First run may take a while (git blame); later runs use a cache under .git/okulo/.

6. See the whole map

okulo map --html map.html

Interactive treemap of size × hotspots × health.

Next

• Concepts — how to read the numbers
• Commands — full reference
• Configuration — .okulo.toml