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), now extended to the v2-as-built architecture and the v3 consolidation ahead.
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 a file on disk. A separate process (the CLI hook) writes ~/.codogotchi/state.json; the app polls that file 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 → v3 (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 motivate.

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).

Reference (13–17)

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

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 v3 needs. The v3 Polish Roadmap discussion lays out what’s already shipped in v2.6.0 and what’s still open — UX gaps, the Sessions panel, distribution/notarization, an architectural consolidation pass, and fleshing out the RPG tab. It’s not a finalized scope, so if you want to argue for, against, or add a direction, that thread is the place.
  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.