🎃 GitGotchi

Your terminal is haunted now. These days AI agents write a lot of the commits, and GitGotchi is the little spirit that lives in your repo and watches them land. Feed it commits, keep it company while your agent works, and see what it grows into.

Every form is a real 3D model, raymarched and cel-shaded into pixel art right in your terminal.

🚀 Try it

pip install gitgotchi
gitgotchi demo

demo opens a throwaway repo where you, Claude and Copilot take turns committing, so you can watch a pumpkin grow into a Poltergeist in about thirty seconds.

🌱 Haunt your own repo

cd your-project
gitgotchi install   # every commit now feeds your companion
gitgotchi adopt     # raise it on the history you already have
gitgotchi haunt     # open the live pane

Keep gitgotchi haunt open in a split next to the terminal where you or your agent are working. Every commit gets a reaction, agent commits glitch the screen, and evolutions play out live. It watches every local branch, so it sees commits from other worktrees too. Commits that arrive by git pull aren't yours, so they don't feed your companion.

👾 Possession

GitGotchi spots commits written by AI agents (Claude, Copilot, Codex, Cursor, Devin, Aider, Gemini, Windsurf, Cline, Amp) from their Co-Authored-By trailers, "Generated with" footers and bot accounts. They feed your companion like any other commit, and they also fill its possession meter. Once agents have written at least half of 6+ commits, your companion becomes a Poltergeist.

When git isn't attached to a terminal (an agent running git commit, for example), the hook prints a single line instead of the full pet, so it doesn't flood the agent's context.

🖼️ Share it

gitgotchi card

Saves a 1200×630 card, sized for LinkedIn and other link previews:

🔮 Séance

gitgotchi seance

Your companion digs through the history for its ghosts: the oldest TODO still in the code, the file nobody has opened in ages, the biggest deletion, commits made between midnight and 4am, and the first commit an AI agent wrote. Then it tells you a story about them. Set ANTHROPIC_API_KEY (or put it in a .env file) to have Claude tell it; otherwise your companion tells it in its own words. With a key set, the findings (file names, TODO text and recent commit messages) are sent to the Anthropic API to write the story. GitGotchi reads only ANTHROPIC_API_KEY from .env and ignores everything else in it.

🎮 All commands

🌕 Evolution

Quality drifts toward the score of each commit:

Go a day without committing and your companion gets hungry; after a week it goes dormant.

🖥️ Terminals

GitGotchi draws with true-color half-block characters, so it works in practically every modern terminal, including VS Code, iTerm2, Kitty, WezTerm, Ghostty, Windows Terminal and macOS Terminal. gitgotchi card also shows the image inline in terminals that support it. Set GITGOTCHI_GRAPHICS=blocks to turn that off.

🗂️ Where state lives

Your companion lives in .git/gitgotchi/state.db, inside the repository's git directory. It never shows up in git status, can't be committed, and every git worktree of the repo shares the same pet, so commits your agents make in their own worktrees count too.

🛠️ Development

git clone https://github.com/Srikarmk/Gitgotchi.git
cd Gitgotchi
pip install -e ".[dev]"
pytest
python scripts/render_assets.py   # regenerate the images in docs/

See INSTALL.md for more and CHANGELOG.md for release notes.

License

MIT - see LICENSE.