🎃 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. Add --gif for one where your companion moves (needs pip install "gitgotchi[gif]").

For your README, gitgotchi badge saves a small SVG with your companion's portrait and form, and prints the Markdown to paste in. Run it again whenever your companion evolves.

📟 In your status bar

gitgotchi-statusline prints one line about the companion in the current repo, for example 👾 Boo the Poltergeist · 63% possessed · hungry. It starts in about 50 ms and prints nothing outside a haunted repo, so it's safe to leave on everywhere.

Claude Code: add this to ~/.claude/settings.json

"statusLine": {"type": "command", "command": "gitgotchi-statusline"}

tmux: add this to ~/.tmux.conf

set -g status-right '#(cd #{pane_current_path} && gitgotchi-statusline --plain)'

gitgotchi-statusline --setup prints these snippets, plus one for Starship.

🔕 How much the hook says

gitgotchi config line             # one line per commit in this repo
gitgotchi config off --global     # silent everywhere
gitgotchi config full             # the whole pet (the default)

It's stored in git config as gitgotchi.output, so a repo's setting wins over the global one. When an agent runs git commit without a terminal, the hook always keeps it to one line.

🩺 Something not working?

gitgotchi doctor

Checks git, the hook and the Python it points at, the pet database, your terminal's colors and size, and whether stories can use Claude, with a fix for anything that's wrong. Include its output when you open an issue; it never shows your API key.

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