Your real work builds a virtual city. A native macOS ambient companion that turns your closed tasks, git commits, and notes into an ever-growing isometric city — kept always behind your other windows so it lives on your desktop without distracting you.
You give CommitPyramid a stream of "things you closed" — completed tasks from your task manager, commits from your repositories, or [x] checkboxes in your notes. Each item builds a tile in your city. Long-untouched projects fall into disrepair; revived projects bloom again. Stages, evolution chains, biomes, and NPC citizens emerge from your real activity.
It is not gamification with badges. It is ambient feedback — a city that quietly reflects what you actually did this week.
This project is in active development. Core mechanics work; the visual layer relies on procedural placeholder sprites until contributors generate themed PNG assets via the catalog in docs/asset-prompts.md.
Convergence (May 2026): 17 of 19 features done, 2 partial. See docs/architecture.md for the technical map.
Requirements:
- macOS 14 (Sonoma) or later
- Xcode 15+ (Command Line Tools are not enough — the SpriteKit + XCTest stack needs the full Xcode)
- Swift 5.10
Build and run:
git clone https://github.com/Kvazemorda/CommitPyramid.git
cd CommitPyramid
swift build
swift run CommitPyramidThe app starts as a translucent window pinned behind all other apps. Press ⌘⌥G anywhere to bring it to the foreground (explore mode) and back.
CommitPyramid reads from event sources, each implementing the EventSource protocol:
tasks.jsonlwatcher — one line per completed task. The simplest source, written by an external script or a cron job.- Notes/Folder watcher — scans
.mdfiles for[x]checkboxes, headings, bullets, or frontmatter, configurable in Settings. - Git watcher — runs
git log --since=<last-check-ts>on configured local repositories, optionally derives weight from diff size and category from conventional-commit prefix. - In-app journal — type a task directly in the side panel or contextually by clicking an empty tile.
Every event becomes a task_completed line in events.jsonl. The engine deterministically builds units, raises stages, ages buildings into ruins, and animates citizens — all replayable from the log alone.
For the full architecture see docs/architecture.md.
There are two main ways to help:
- Read
docs/CONTRIBUTING.md. - Look at issues with the
good first issuelabel. - Fork → branch → pull request.
The city currently renders procedural placeholders for all buildings and biomes — coloured isometric primitives. The visual goal is a Pharaoh-style hand-painted look (sand, ochre, lapis, reed greens). We have a complete prompt catalog for AI image generators (Midjourney, DALL·E, SDXL):
- Read
docs/CONTRIBUTING-ASSETS.md— pipeline from prompt to merged PNG. - Pick any unit or biome from
docs/asset-prompts.md, generate it, open a PR with the PNG. - Every merged sprite immediately replaces its procedural placeholder in the next build — no code changes needed.
docs/concept.md— what CommitPyramid is, who it's for, why.docs/sprite-generation-rules.md— technical and stylistic rules for art assets.docs/log-format.md—tasks.jsonlandevents.jsonlspecification.
MIT. See LICENSE.