Skip to content
Codogotchi for Dummies

Codogotchi for Dummies

A TypeScript / FP developer's field guide to the Codogotchi macOS menubar app — the learning path that drove v2 (per-platform multi-pet), the v2-as-built architecture, the seams that motivated v3, the consolidation as built, and where v4 (screensaver mode) is headed.
Start reading Jump to challenges

The one-sentence mental model

Section titled “The one-sentence mental model”

The Swift app is a pure-ish render function over files on disk. A separate process (the CLI hook) writes per-session slices under ~/.codogotchi/state.d/; the app polls that directory once a second and turns whatever it reads into pixels. In FP terms: render : StateOnDisk → (MenubarIcon, FloatingPet?) — run at 1 Hz.

Core pipeline (01–06)

Maps the state → render spine you need to understand v2. Read in order — each chapter ends with a “prove it to yourself” exercise.

v2 as built → seams (09–10)

The shipped v2 architecture — state.d slices, the window pool, the session lifecycle — then a critical read of its seams and the v3 redesign they motivated.

Hands-on, both eras (07–08 · 11–12)

Tiered-hint challenges and curated resources: 07–08 ramped v1 → v2; 11–12 do the same for v2 → v3 (seam-breaking exercises, notarization/Sparkle reading).

v3 as built (13)

What phases 16–20 actually landed — typed WindowKey, drawers, derive/diff/apply, fold identity, sticky slice clocks — and how Chapter 10’s seams were closed.

v4 roadmap (14)

Where v4 is going: Screensaver Mode. Codogotchi as a real macOS screensaver — the disk contract already supports it, the trigger decision, the sandbox constraints, and the fullscreen panel-layout design problem.

Reference (15–20)

Dev helpers, platform APIs (NSPanel, SpriteKit, AppKit), the procedural-effects engine, the ~/.codogotchi disk contract, the App Store requirements primer, and the v3.0.0 domain-language dictionary.

Swift for TS devs (05)

Maps every Swift idiom you’ll trip over — @MainActor, weak self, protocols, Result — to a TypeScript equivalent you already know.

Ready to actually contribute?

Section titled “Ready to actually contribute?”

Reading this guide gets you the mental model. Here’s how to turn that into a merged PR:

  1. Fork cesarnml/codogotchi, then follow CONTRIBUTING.md for setup (bun install, bun run ci:quiet).
  2. Pick an issue sized to your comfort level. Issues are labeled difficulty: 1 through 8 — start with a 2 or 3 if it’s your first PR here.
    Terminal window
    gh issue list --label "difficulty: 2"
  3. See what’s next. v3 has shipped as of v3.0.2 — notarized DMG, Sparkle auto-updates, a Homebrew cask, the Sessions panel, and the Track 4 consolidation pass, all documented in Chapter 13. The live frontier is v4: Chapter 14 covers the committed headline feature (screensaver mode) as currently planned. For general contribution surfaces, check the pinned bug hunt, platform compatibility reports, and pet/sprite showcase issues. (The v3 Polish Roadmap discussion is kept for historical context on how v3’s scope came together — most of what it lists has since shipped.)
  4. Questions are welcome. Open an issue with the question label, or ask in your PR — see the Code of Conduct for the full welcome note to newcomers.