Inspiration

Failing CI runs and stale issues arrive as notifications we have all learned to ignore, and a repo can go quiet for months before anyone notices it is dead. The 90s virtual pet was impossible to ignore, so I brought it back from the grave as a live view of repo health.

What it does

  • Adopt any repo. Public repos work without an account; the pet is seeded from real CI runs, pushes and stale issues. HP comes from CI, Fullness from pushes, Sanity from issues.
  • Death and resurrection that mean something. Red CI kills the pet and REVIVE is refused until CI is green. A revived pet rises as a ghost for a day and carries a scar for every comeback. A repo that died, came back and stayed healthy for a week earns the rare Necromancer.
  • A live README badge. One click (ADD TO README) puts the pet in your README, and it keeps following the repo on its own, so every visitor sees whether the project is alive.
  • One pet per repo, cared for by its team. Sign in with GitHub: collaborators with push access are keepers; everyone else can look. Private repos work through a read-only GitHub App, encrypted and invisible to outsiders.
  • Kiro closes the loop. A Kiro hook turns code smells into poop on the pet. Summon Kiro (HEAL, or /summon-healer over MCP) hands Kiro the real findings, including an excerpt of the failing CI log. Kiro fixes the code spec-first and runs the tests; CI turns green and the pet climbs out of the grave. GitGotchi itself never writes to your repo.

How I built it

Next.js 16 on Vercel, React 19, TypeScript and Tailwind; Upstash Redis for storage; a GitHub App for sign in and webhooks; a pure TypeScript pet engine shared by the server and the browser; pixel-art sprites and 8-bit sounds synthesized with the Web Audio API. An MCP server with seven tools lets Kiro read, diagnose and badge the pet, and it is also packaged as a Kiro Power.

How I used Kiro

  • Kiro IDE: I wrote the PRD and BRD; Kiro turned them into five feature specs (EARS requirements, design, tasks) and ran the tasks. The many one-by-one approvals were the main friction, solved later with "Approve for me" and narrow Always-allow rules. Kiro's built-in rule that blocks the agent from editing its own .kiro/settings showed up too, and I kept it.
  • Kiro Web: for deployment I moved to Kiro Web, where the agent worked directly with GitHub and Vercel: domains, environment variables, the GitHub App, accounts and privacy, the Necromancer and CI. Every change went spec first, then code, then a test that fails without it, then a PR merged only on green CI and a production check.
  • Hooks: a PostFileSave hook reports console.log, debugger and TODOs to the pet; a spec-sync hook checks the engine against its spec. Tested live in the Kiro IDE and shown in the video: saving a console.log made the pet poop, and removing it cleaned the poop.
  • Steering: a "report only what actually ran" rule made every status update checkable.
  • MCP and Powers: the gitgotchi MCP server (get_pet_status, diagnose_pet, add_badge and more), tested live in the Kiro IDE and shown in the video: /summon-healer found the code smell, Kiro removed it and the next diagnosis came back clean. The server is also bundled as a Power.
  • Property-based testing: fast-check properties guard the pet engine's invariants. Specs caught real bugs: two ways an outsider could tell a private repo existed, and a CI run counted twice.

Challenges I ran into

  • Chrome flagged the GitHub OAuth callback on my young custom domain as phishing. I moved sign in to a separate host with a single-use ticket handoff and asked Google for a review.
  • Keeping free-tier quotas safe: a 30-second read cache, adaptive polling and per-IP rate limits.
  • Making a dead pet's comeback honest: resyncs from GitHub must not skip the "rising ghost" stage.

Accomplishments that I'm proud of

A complete, live product rather than a prototype: private repos with encrypted storage, a security review (CSP, token revocation on sign out, rate limits), 322 unit tests plus browser tests in CI, and a pet that dies and comes back in real READMEs.

What I learned

Write the product documents yourself and let Kiro turn them into specs; connect GitHub and hosting early; and keep a steering rule that forbids invented results.

What's next for GitGotchi

A health history chart, opt-in alerts only when a pet dies or comes back, and an opt-in "Hall of Resurrection" for repos that became Necromancers.

Built With

  • fast-check
  • github-api
  • github-app
  • kiro
  • kiro-ide
  • kiro-web
  • mcp
  • nextjs
  • react
  • redis
  • tailwindcss
  • typescript
  • upstash
  • vercel
  • vitest
  • web-audio-api
Share this project:

Updates

Submission history