Yog-Sothoth

The Key and the Gate

A personal infrastructure CLI tool written in Go. Not something you work inside — it's the ritual you run at the threshold of a project. It eliminates friction at project lifecycle boundaries: starting clean, staying clean, validating everything.

Pairs with Azathoth (AI/MCP layer) as a personal dev acceleration system.

Yog creates the world. Azathoth understands it. You do everything.

Commands

reborn flags: --deep (also nuke lockfiles), --full (recursive workspace clean), --dry-run, --no-install

Node.js is never supported. Deno and Bun only.

Install

Go binary

go build -o ~/go/bin/yog ./src/yog_sothoth

Ensure ~/go/bin is in your $PATH. On NixOS, add it via home.sessionPath in home-manager, or use the uv wrapper below.

uv wrapper (NixOS / read-only systems)

uv tool install --editable .

This installs a yog shim via the Python wrapper that proxies to the compiled Go binary — no PATH surgery required.

Architecture

Strict 3-layer separation — non-negotiable:

src/yog_sothoth/
├── main.go          ← calls cmd.Execute(), nothing else
├── cmd/             ← CLI layer: Cobra only, zero logic
├── internal/
│   ├── deps/        ← reborn logic
│   ├── env/         ← .env management logic
│   └── health/      ← doctor check logic
└── pkg/             ← shared config types + Lip Gloss UI styles

• cmd/ defines flags and delegates. Never contains business logic.
• internal/ does all real work. Never knows about Cobra.
• pkg/ holds only what's genuinely shared across layers.

Tech Stack

• Language: Go — Cobra · Viper · Lip Gloss · godotenv
• Python shim: uv workspace · uv tool install --editable .

License

This project is licensed under the terms of the MIT license.