MONOLITH — Digital Landslide Laboratory

A terminal-native observatory that treats a git repository as a geologic body. It fixes nothing — it only observes, records, and presents the slow collapse of a codebase.

MONOLITH sits on top of any git repository as a digital landslide observatory. Every commit becomes a sediment layer, every conflict a fault, every revert an erosion layer. It computes a "mass" for each file (lines × coupling × churn) and lets heavy objects settle under gravity. It weathers untouched files day by day through an access half-life until only skeletons remain. It raises a black stone in the corner of your terminal that devours stale branches, hanging tasks and uncommitted stashes as the repository decays. With the dead-serious aesthetics of a USGS seismograph, it keeps monitoring landslide risk, translates infrastructure death countdowns into low-frequency pulses and static, and can fossilize the whole state into a one-of-a-kind ASCII mudslide photograph at any moment.

中文版

---

Screenshots

Interactive observatory — four-panel TUI

Stratigraphy profile — every commit as a sediment layer

Mass & gravity — heavy files settle, light ones float; excavate the heaviest and the slope answers

Erosion table — half-life weathering until only skeletons remain

The black stone — devouring stale branches, todos and stashes

Seismic station — landslide risk report with seismograph trace

Collapse radio — risk translated into low-frequency pulses and static

Mudslide snapshot — a deterministic ASCII disaster photograph of your repo

---

Install

Requires Python ≥ 3.10.

pip install rich GitPython
# Optional, for parsing TLS certificate expiry:
pip install cryptography

cd monolith
pip install -e .

Raise a demo code-mountain with a full built-in decay history (18 months, 35 strata, faults / erosion / expiring certificates / dying dependencies):

monolith demo
monolith --repo ~/.monolith/demo

Quick start

monolith                      # enter the interactive observatory on the current git repo
monolith --repo /path/to/repo # point at a specific repository

Observation commands

Command	Description
monolith / monolith observe	four-panel interactive observatory (recommended)
monolith strata	print the static stratigraphy profile (oldest at the bottom)
monolith physics	run the mass/gravity settling simulation and demo a cascade collapse
monolith erosion	print the half-life erosion table (weathered / skeleton / tombstone)
monolith risk	print the landslide risk report with a seismograph trace snapshot
monolith monolith	the black stone's feeding report
monolith radio	translate risk into low-frequency pulses + static (WAV / play)
monolith snapshot	generate an ASCII mudslide photograph
monolith demo	raise a demo code-mountain

Common flags: --repo PATH selects the repository; --width / --height control output size.

Radio

monolith radio --repo /tmp/demo --out /tmp/collapse.wav --seconds 10   # synthesize to WAV
monolith radio --play                                                  # try aplay/afplay/ffplay
monolith radio --morse "SLOPE 5.3"                                     # print Morse only

Higher risk → faster pulse rhythm, higher frequency, stronger static.

Snapshot

monolith snapshot --out /tmp/mudslide.txt        # save the plain-text photograph
monolith snapshot                                # print directly (adapts to terminal width)

Snapshots are deterministically seeded from the repo HEAD hash + paths — every photograph of the same repository is unique and fully reproducible.

Interactive observatory (TUI)

╔ MONOLITH ● DIGITAL LANDSLIDE LABORATORY ── subject /repo ── head abc123 ── 2026-08-13 ... ╗
 RISK 05.3 MODERATE │ decay 25% │ commits 35 │ alive 27 │ dead 2 ...
╔ STRATIGRAPHY 35 layers ═══╗ ╔ MASS/GRAVITY settling ════╗
║▸26-08-09  132 ▒▒.▒▒▒▒▒·...▒ · ║ ║▲ old_todo.py ██░░░     ║
║26-08-03  132 ▒▒▒▒▒▒▒,▒▒▒▒▒▒▒ · ║ ║▼ engine.py  ████████  ║
║ ...                         ║ ╚════════════════════════╝
╚════════════════════════════╝ ╔ EROSION t½=60d [R]=reinforce ╗
╔ SEISMOGRAPH / TRANSMISSION ═══╗                       ████ ╗
║LANDSLIDE MAGNITUDE 05.3 MODERATE                   ██████ ║
║▂▃▄▅▆▇█▇▆▅▄▃▂                               ...    ██████ ║
╚═══════════════════════════════════════════════════════════╝
[↑/↓] layers [d] excavate [r] rebuild [R] reinforce [s] snapshot [q] quit

Key	Action
↑ / ↓	move the cursor through sediment layers (back in time / back to now)
PgUp / PgDn, Home / End	large scroll steps
d	excavate the heaviest file — large enough, it triggers a cascade collapse of the tree
r	reset the physics simulation (back to the present)
R	reinforce a weathered file, restoring it to full substance
s	generate and save a mudslide photograph
q / Esc	quit

Core concepts

Stratigraphy

Every commit is a sediment layer: old layers at the bottom, new ones on top. Merges are purple fault sutures \, reverts are red erosion layers ~, conflicts are fracture zones #; an unconformity (dotted line) appears when two commits are more than 120 days apart. Each layer is labeled with its date and impact (lines added/removed); the sedimentary texture is deterministically derived from the commit hash.

Mass & gravity

File mass = lines × (1 + 0.45 × references) × (1 + log₂(churn + 1)). The gravity engine bubble-settles frame by frame: heavy objects sink (▼), light ones float up (▲). Removing a sufficiently large file triggers a cascade collapse on its directory subtree — the whole subtree falls frame by frame and ends as talus at the mountain foot.

Erosion

Weathering by access half-life (default 60 days): fresh = 0.5^(days since last touch / half-life). Substance ▓ → flaking ▒ → skeleton [e…y] → tombstone † once deleted. Press R to reset the observed last_touch to now (reinforce).

The black stone

A black monolith stands in the corner of the terminal. It feeds on repository decay: stale branches (idle processes), TODO/FIXME markers (hanging tasks), stashes and uncommitted changes — growing with the decay index and the amount devoured.

Landslide risk

USGS seismograph style. Six weighted factors: expiring TLS certificates (parsed via cryptography from *.pem/.crt), deeply coupled core files that are actively eroding, dying dependency manifests, commit pulse velocity, overall decay, and revert erosion frequency. Risk readings feed a ring buffer and render as a seismograph trace; crossing thresholds raises alerts.

Radio

Risk is translated into acoustic signals: pulse interval 0.95 − 0.75×risk s, pulse frequency 45 + 75×risk Hz, static intensity scaling with risk, and a 30 Hz infrasound floor. Outputs 22050 Hz 16-bit WAV.

Mudslide snapshot

Deterministically seeded from repository features, drawing a collapsing mountain: stratigraphy profile, fault cracks, falling boulders labeled with filenames, a monolith silhouette on the ridge, talus, and survey data. Every photograph of the same repo is different and reproducible.

Compatibility

• Python ≥ 3.10, rich + GitPython, pure TUI (no GUI).
• Linux / macOS native terminals (termios raw keyboard reading).
• Windows Terminal / WSL2: keys via msvcrt; WSL2 behaves identically to Linux.
• Requires an ANSI color terminal; Linux (Ubuntu 22.04) is the primary battleground.
• In non-TTY environments (pipes, CI), observe degrades to printing a single static frame.

Architecture

monolith/
  cli.py        command-line entry and all observation commands
  analytics.py  git geology analysis layer (Commit / FileRecord / deps / certs)
  strata.py     stratigraphy profile rendering
  physics.py    mass/gravity engine + cascade collapse
  erosion.py    half-life erosion
  monolith.py   the black stone
  risk.py       USGS landslide risk factors + seismograph buffer
  radio.py      radio audio synthesis (WAV / play / Morse)
  snapshot.py   ASCII mudslide photograph
  tui.py        unified interactive observatory (keyboard + Live rendering)
  keys.py       cross-platform raw keyboard reading
  aesthetics.py USGS theme and unified color scheme
  ascii.py      fixed-width ASCII panel drawing
  demo.py       demo code-mountain generator