gitgotchi 0.1.2__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. gitgotchi-0.3.0/CHANGELOG.md +57 -0
  2. gitgotchi-0.3.0/INSTALL.md +134 -0
  3. {gitgotchi-0.1.2 → gitgotchi-0.3.0}/LICENSE +21 -21
  4. gitgotchi-0.3.0/MANIFEST.in +9 -0
  5. gitgotchi-0.3.0/PKG-INFO +178 -0
  6. gitgotchi-0.3.0/README.md +137 -0
  7. gitgotchi-0.3.0/pyproject.toml +81 -0
  8. {gitgotchi-0.1.2 → gitgotchi-0.3.0}/setup.cfg +4 -4
  9. gitgotchi-0.3.0/src/gitgotchi/__init__.py +3 -0
  10. gitgotchi-0.3.0/src/gitgotchi/__main__.py +5 -0
  11. gitgotchi-0.3.0/src/gitgotchi/cli.py +360 -0
  12. {gitgotchi-0.1.2/src → gitgotchi-0.3.0/src/gitgotchi}/db/__init__.py +1 -1
  13. {gitgotchi-0.1.2/src → gitgotchi-0.3.0/src/gitgotchi}/db/migrations.py +100 -100
  14. {gitgotchi-0.1.2/src → gitgotchi-0.3.0/src/gitgotchi}/db/models.py +112 -92
  15. {gitgotchi-0.1.2/src → gitgotchi-0.3.0/src/gitgotchi}/db/state_manager.py +383 -277
  16. gitgotchi-0.3.0/src/gitgotchi/demo.py +72 -0
  17. gitgotchi-0.3.0/src/gitgotchi/haunt.py +207 -0
  18. gitgotchi-0.3.0/src/gitgotchi/history.py +70 -0
  19. {gitgotchi-0.1.2/src → gitgotchi-0.3.0/src/gitgotchi}/hooks/__init__.py +1 -1
  20. gitgotchi-0.3.0/src/gitgotchi/hooks/installer.py +152 -0
  21. gitgotchi-0.3.0/src/gitgotchi/hooks/post_commit.py +81 -0
  22. gitgotchi-0.3.0/src/gitgotchi/paths.py +61 -0
  23. {gitgotchi-0.1.2/src → gitgotchi-0.3.0/src/gitgotchi}/pet/__init__.py +1 -1
  24. gitgotchi-0.3.0/src/gitgotchi/pet/possession.py +56 -0
  25. gitgotchi-0.3.0/src/gitgotchi/pet/quality.py +98 -0
  26. gitgotchi-0.3.0/src/gitgotchi/pet/renderer.py +200 -0
  27. {gitgotchi-0.1.2/src → gitgotchi-0.3.0/src/gitgotchi}/pet/states.py +161 -116
  28. gitgotchi-0.3.0/src/gitgotchi/pet/theme.py +83 -0
  29. gitgotchi-0.3.0/src/gitgotchi/render/__init__.py +49 -0
  30. gitgotchi-0.3.0/src/gitgotchi/render/card.py +107 -0
  31. gitgotchi-0.3.0/src/gitgotchi/render/effects.py +96 -0
  32. gitgotchi-0.3.0/src/gitgotchi/render/font.py +88 -0
  33. gitgotchi-0.3.0/src/gitgotchi/render/forms.py +477 -0
  34. gitgotchi-0.3.0/src/gitgotchi/render/raster.py +217 -0
  35. gitgotchi-0.3.0/src/gitgotchi/render/scene.py +104 -0
  36. gitgotchi-0.3.0/src/gitgotchi/render/terminal.py +130 -0
  37. {gitgotchi-0.1.2/src → gitgotchi-0.3.0/src/gitgotchi}/seance/__init__.py +1 -1
  38. gitgotchi-0.3.0/src/gitgotchi/seance/hauntings.py +146 -0
  39. gitgotchi-0.3.0/src/gitgotchi/seance/story_gen.py +164 -0
  40. gitgotchi-0.3.0/src/gitgotchi.egg-info/PKG-INFO +178 -0
  41. gitgotchi-0.3.0/src/gitgotchi.egg-info/SOURCES.txt +55 -0
  42. gitgotchi-0.3.0/src/gitgotchi.egg-info/entry_points.txt +2 -0
  43. gitgotchi-0.3.0/src/gitgotchi.egg-info/requires.txt +14 -0
  44. gitgotchi-0.3.0/src/gitgotchi.egg-info/top_level.txt +1 -0
  45. gitgotchi-0.3.0/tests/conftest.py +14 -0
  46. gitgotchi-0.3.0/tests/test_cli.py +50 -0
  47. gitgotchi-0.3.0/tests/test_haunt.py +54 -0
  48. gitgotchi-0.3.0/tests/test_hauntings.py +40 -0
  49. gitgotchi-0.3.0/tests/test_history.py +87 -0
  50. gitgotchi-0.3.0/tests/test_hooks.py +101 -0
  51. gitgotchi-0.3.0/tests/test_possession.py +31 -0
  52. gitgotchi-0.3.0/tests/test_quality.py +58 -0
  53. gitgotchi-0.3.0/tests/test_render.py +55 -0
  54. gitgotchi-0.3.0/tests/test_state_manager.py +73 -0
  55. gitgotchi-0.3.0/tests/test_states.py +45 -0
  56. gitgotchi-0.3.0/tests/test_story.py +90 -0
  57. gitgotchi-0.1.2/.kiro/specs/git_hook_integration.md +0 -46
  58. gitgotchi-0.1.2/.kiro/specs/pet_state_system.md +0 -51
  59. gitgotchi-0.1.2/.kiro/specs/project_setup.md +0 -27
  60. gitgotchi-0.1.2/.kiro/steering/code_style.md +0 -46
  61. gitgotchi-0.1.2/.kiro/steering/project_voice.md +0 -52
  62. gitgotchi-0.1.2/KIRO_USAGE.md +0 -204
  63. gitgotchi-0.1.2/MANIFEST.in +0 -13
  64. gitgotchi-0.1.2/PKG-INFO +0 -78
  65. gitgotchi-0.1.2/README.md +0 -38
  66. gitgotchi-0.1.2/gitgotchi.egg-info/PKG-INFO +0 -78
  67. gitgotchi-0.1.2/gitgotchi.egg-info/SOURCES.txt +0 -36
  68. gitgotchi-0.1.2/gitgotchi.egg-info/entry_points.txt +0 -2
  69. gitgotchi-0.1.2/gitgotchi.egg-info/requires.txt +0 -12
  70. gitgotchi-0.1.2/gitgotchi.egg-info/top_level.txt +0 -1
  71. gitgotchi-0.1.2/gitgotchi_spec.md +0 -1580
  72. gitgotchi-0.1.2/pyproject.toml +0 -76
  73. gitgotchi-0.1.2/requirements.txt +0 -6
  74. gitgotchi-0.1.2/setup.py +0 -64
  75. gitgotchi-0.1.2/src/__init__.py +0 -13
  76. gitgotchi-0.1.2/src/cli.py +0 -182
  77. gitgotchi-0.1.2/src/hooks/installer.py +0 -128
  78. gitgotchi-0.1.2/src/hooks/post_commit.py +0 -70
  79. gitgotchi-0.1.2/src/pet/evolution.py +0 -5
  80. gitgotchi-0.1.2/src/pet/renderer.py +0 -208
  81. gitgotchi-0.1.2/src/seance/git_analyzer.py +0 -5
  82. gitgotchi-0.1.2/src/seance/story_gen.py +0 -177
  83. gitgotchi-0.1.2/src/seance/templates.py +0 -3
  84. {gitgotchi-0.1.2 → gitgotchi-0.3.0/src}/gitgotchi.egg-info/dependency_links.txt +0 -0
@@ -0,0 +1,57 @@
1
+ # Changelog
2
+
3
+ ## 0.3.0 - Halloween
4
+
5
+ ### New
6
+
7
+ - **3D pixel-art companion.** Every form is a 3D model, raymarched and cel-shaded into pixel art and
8
+ drawn in the terminal with true-color half blocks. It bobs, blinks and spins, on a night-sky stage.
9
+ - **Halloween all year.** Pumpkin replaces Egg, and everything got a new look and voice: cute early
10
+ forms, eerie Demon, Wraith and Poltergeist.
11
+ - **Possession.** Commits written by AI agents are recognised from their trailers, footers and bot
12
+ accounts. They fill a possession meter and unlock the new **Poltergeist** form.
13
+ - `gitgotchi haunt`: a live pane that reacts to every commit as it lands, with sparkles, possession
14
+ glitches for agent commits, and evolution animations.
15
+ - `gitgotchi adopt`: raise your companion on the history a repo already has.
16
+ - `gitgotchi card`: a shareable 1200x630 PNG.
17
+ - `gitgotchi seance`: ghost stories built from your repo's real history (oldest TODO, forgotten files,
18
+ biggest deletion, late-night commits, the first agent commit). `story` still works as an alias.
19
+ - `gitgotchi demo`: watch a throwaway repo get haunted.
20
+
21
+ ### Changed
22
+
23
+ - The hook prints a single line when git isn't attached to a terminal, so agents running `git commit`
24
+ don't get the full pet in their output.
25
+ - Evolution plays an animation in real terminals.
26
+ - `numpy` is now a dependency.
27
+ - Databases from 0.2.0 are upgraded automatically.
28
+
29
+ ## 0.2.0
30
+
31
+ ### Fixed
32
+
33
+ - The package is now installed as `gitgotchi` instead of `src`. The old name collided with any
34
+ project that has its own `src/` package and made the post-commit hook fail there.
35
+ - `gitgotchi uninstall` now really removes the hook (it used to leave the command behind).
36
+ - Running a command from a subdirectory no longer creates a second, empty companion.
37
+ - `.gitgotchi/` is excluded from git automatically so the database can't be committed by accident.
38
+ - Mood now reflects how long it's been since the last commit when you check on your companion.
39
+ - Angel was unreachable; quality is now scored from each commit (see README).
40
+ - `gitgotchi story` uses a current Claude model and shows why when it falls back to a built-in story.
41
+ - `.env` files are actually loaded.
42
+ - `gitgotchi version` reports the real version.
43
+
44
+ ### Changed
45
+
46
+ - Hooks respect `core.hooksPath` and git worktrees, and are kept alongside any existing hook.
47
+ Running `gitgotchi install` again updates an old hook in place.
48
+ - Requires `anthropic>=1.0` and `typer>=0.12`.
49
+ - Added `python -m gitgotchi`.
50
+
51
+ ## 0.1.3
52
+
53
+ - PyPI README update.
54
+
55
+ ## 0.1.0 - 0.1.2
56
+
57
+ - Initial release.
@@ -0,0 +1,134 @@
1
+ # GitGotchi Installation Guide
2
+
3
+ ## Install
4
+
5
+ ```bash
6
+ pip install gitgotchi
7
+ gitgotchi --help
8
+ ```
9
+
10
+ Or, to keep it isolated from your other Python packages:
11
+
12
+ ```bash
13
+ pipx install gitgotchi
14
+ ```
15
+
16
+ ## Setup
17
+
18
+ 1. **Go to any git repository**:
19
+
20
+ ```bash
21
+ cd your-project
22
+ ```
23
+
24
+ 2. **Install the hook and meet your companion**:
25
+
26
+ ```bash
27
+ gitgotchi install
28
+ gitgotchi adopt # optional: raise it on the history you already have
29
+ gitgotchi status
30
+ ```
31
+
32
+ Want to see it first? `gitgotchi demo` runs in a throwaway repo.
33
+
34
+ 3. **Make commits and watch your companion grow!** Keep `gitgotchi haunt` open in a split to see
35
+ it react live.
36
+
37
+ ```bash
38
+ git add .
39
+ git commit -m "feat: add cool feature"
40
+ gitgotchi status # Your companion just got fed! 🌟
41
+ ```
42
+
43
+ 4. **Optional: AI stories.** Get an API key from the [Anthropic Console](https://console.anthropic.com)
44
+ and set it:
45
+
46
+ ```bash
47
+ export ANTHROPIC_API_KEY='your-key-here'
48
+ # or
49
+ echo "ANTHROPIC_API_KEY=your-key-here" >> .env
50
+ ```
51
+
52
+ ## Requirements
53
+
54
+ - Python 3.10 or higher
55
+ - Git installed and configured
56
+ - A git repository (run `git init` if needed)
57
+
58
+ ## Troubleshooting
59
+
60
+ ### "Command not found: gitgotchi"
61
+
62
+ Make sure the package is installed and your Python scripts directory is on your PATH:
63
+
64
+ ```bash
65
+ pip show gitgotchi
66
+ ```
67
+
68
+ `pipx install gitgotchi` takes care of PATH for you.
69
+
70
+ ### "No git repository found"
71
+
72
+ GitGotchi lives inside a git repository. Initialize one first:
73
+
74
+ ```bash
75
+ git init
76
+ ```
77
+
78
+ ### My companion stopped eating after I recreated my virtualenv
79
+
80
+ The hook remembers which Python it was installed with. Re-run `gitgotchi install` from the new
81
+ environment and it will update the hook in place.
82
+
83
+ ### Upgrading from 0.1.x
84
+
85
+ 0.1.x installed its code as a package named `src`, which broke the hook in projects that have
86
+ their own `src/` package. After upgrading, run `gitgotchi install` once in each repository to
87
+ replace the old hook. Your companion's state is kept.
88
+
89
+ ## Development
90
+
91
+ ```bash
92
+ git clone https://github.com/Srikarmk/Gitgotchi.git
93
+ cd Gitgotchi
94
+ pip install -e ".[dev]"
95
+ pytest
96
+ ```
97
+
98
+ ### Building
99
+
100
+ ```bash
101
+ python -m build
102
+ # dist/gitgotchi-<version>.tar.gz
103
+ # dist/gitgotchi-<version>-py3-none-any.whl
104
+ ```
105
+
106
+ ### Testing the build in a clean environment
107
+
108
+ ```bash
109
+ python -m venv /tmp/gg-test
110
+ source /tmp/gg-test/bin/activate # On Windows: \tmp\gg-test\Scripts\activate
111
+ pip install dist/gitgotchi-*.whl
112
+ gitgotchi version
113
+ deactivate
114
+ ```
115
+
116
+ ### Releasing
117
+
118
+ Bump `__version__` in `src/gitgotchi/__init__.py`, add a CHANGELOG entry, then tag:
119
+
120
+ ```bash
121
+ git tag v0.3.0
122
+ git push origin v0.3.0
123
+ ```
124
+
125
+ The Publish workflow builds the package and uploads it to PyPI.
126
+
127
+ ## Uninstallation
128
+
129
+ ```bash
130
+ gitgotchi uninstall # in each repo
131
+ pip uninstall gitgotchi
132
+ ```
133
+
134
+ Enjoy your new companion! 👻✨
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2024 GitGotchi Team
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2024 GitGotchi Team
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,9 @@
1
+ include README.md
2
+ include LICENSE
3
+ include CHANGELOG.md
4
+ include INSTALL.md
5
+ recursive-include tests *.py
6
+ global-exclude __pycache__
7
+ global-exclude *.py[co]
8
+ prune docs
9
+ prune previews
@@ -0,0 +1,178 @@
1
+ Metadata-Version: 2.4
2
+ Name: gitgotchi
3
+ Version: 0.3.0
4
+ Summary: A 3D pixel-art Halloween spirit that haunts your git repo and reacts as you (and your AI agents) commit
5
+ Author-email: M K Sai Srikar <Srikarmks@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Srikarmk/Gitgotchi
8
+ Project-URL: Repository, https://github.com/Srikarmk/Gitgotchi
9
+ Project-URL: Issues, https://github.com/Srikarmk/Gitgotchi/issues
10
+ Project-URL: Changelog, https://github.com/Srikarmk/Gitgotchi/blob/main/CHANGELOG.md
11
+ Keywords: git,terminal,pet,companion,stardew-valley,ai,tamagotchi,devtools,halloween
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Topic :: Software Development :: Version Control :: Git
17
+ Classifier: Topic :: Games/Entertainment :: Simulation
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Requires-Python: >=3.10
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Requires-Dist: rich>=13.7.0
28
+ Requires-Dist: gitpython>=3.1.40
29
+ Requires-Dist: anthropic>=1.0.0
30
+ Requires-Dist: sqlalchemy>=2.0.36
31
+ Requires-Dist: typer>=0.12.0
32
+ Requires-Dist: python-dotenv>=1.0.0
33
+ Requires-Dist: numpy>=1.24
34
+ Provides-Extra: dev
35
+ Requires-Dist: pytest>=8.0; extra == "dev"
36
+ Requires-Dist: pytest-cov>=5.0; extra == "dev"
37
+ Requires-Dist: build>=1.2; extra == "dev"
38
+ Requires-Dist: ruff>=0.6; extra == "dev"
39
+ Requires-Dist: pillow>=10.0; extra == "dev"
40
+ Dynamic: license-file
41
+
42
+ # 🎃 GitGotchi
43
+
44
+ [![PyPI](https://img.shields.io/pypi/v/gitgotchi)](https://pypi.org/project/gitgotchi/)
45
+ [![CI](https://github.com/Srikarmk/Gitgotchi/actions/workflows/ci.yml/badge.svg)](https://github.com/Srikarmk/Gitgotchi/actions/workflows/ci.yml)
46
+ [![Python](https://img.shields.io/pypi/pyversions/gitgotchi)](https://pypi.org/project/gitgotchi/)
47
+
48
+ **Your terminal is haunted now.** These days AI agents write a lot of the commits, and GitGotchi is the
49
+ little spirit that lives in your repo and watches them land. Feed it commits, keep it company while
50
+ your agent works, and see what it grows into.
51
+
52
+ ![All seven forms](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/forms.png)
53
+
54
+ Every form is a real 3D model, raymarched and cel-shaded into pixel art right in your terminal.
55
+
56
+ ## 🚀 Try it
57
+
58
+ ```bash
59
+ pip install gitgotchi
60
+ gitgotchi demo
61
+ ```
62
+
63
+ `demo` opens a throwaway repo where you, Claude and Copilot take turns committing, so you can watch a
64
+ pumpkin grow into a Poltergeist in about thirty seconds.
65
+
66
+ ## 🌱 Haunt your own repo
67
+
68
+ ```bash
69
+ cd your-project
70
+ gitgotchi install # every commit now feeds your companion
71
+ gitgotchi adopt # raise it on the history you already have
72
+ gitgotchi haunt # open the live pane
73
+ ```
74
+
75
+ Keep `gitgotchi haunt` open in a split next to the terminal where you or your agent are working. Every
76
+ commit gets a reaction, agent commits glitch the screen, and evolutions play out live.
77
+
78
+ ![The haunt pane reacting to commits](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/haunt.gif)
79
+
80
+ ## 👾 Possession
81
+
82
+ GitGotchi spots commits written by AI agents (Claude, Copilot, Codex, Cursor, Devin, Aider, Gemini,
83
+ Windsurf, Cline, Amp) from their `Co-Authored-By` trailers, "Generated with" footers and bot accounts.
84
+ They feed your companion like any other commit, and they also fill its **possession** meter. Once agents
85
+ have written at least half of 6+ commits, your companion becomes a **Poltergeist**.
86
+
87
+ When git isn't attached to a terminal (an agent running `git commit`, for example), the hook prints a
88
+ single line instead of the full pet, so it doesn't flood the agent's context.
89
+
90
+ ## 🖼️ Share it
91
+
92
+ ```bash
93
+ gitgotchi card
94
+ ```
95
+
96
+ Saves a 1200×630 card, sized for LinkedIn and other link previews:
97
+
98
+ ![A sample card](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/card.png)
99
+
100
+ ## 🔮 Séance
101
+
102
+ ```bash
103
+ gitgotchi seance
104
+ ```
105
+
106
+ Your companion digs through the history for its ghosts: the oldest TODO still in the code, the file
107
+ nobody has opened in ages, the biggest deletion, commits made between midnight and 4am, and the first
108
+ commit an AI agent wrote. Then it tells you a story about them. Set `ANTHROPIC_API_KEY` (or put it in a
109
+ `.env` file) to have Claude tell it; otherwise your companion tells it in its own words.
110
+
111
+ ## 🎮 All commands
112
+
113
+ | Command | What it does |
114
+ | --- | --- |
115
+ | `gitgotchi demo` | Watch a throwaway repo get haunted |
116
+ | `gitgotchi install` | Add the post-commit hook (other hooks are kept) |
117
+ | `gitgotchi adopt` | Replay existing history (`--reset` to start over) |
118
+ | `gitgotchi haunt` | Live pane that reacts to every commit |
119
+ | `gitgotchi status` | Your companion and its stats |
120
+ | `gitgotchi seance` | Ghost stories from your repo's history |
121
+ | `gitgotchi card` | Save a shareable PNG |
122
+ | `gitgotchi evolve` | Evolution paths and progress |
123
+ | `gitgotchi pet` | Give it some affection |
124
+ | `gitgotchi name <name>` | Name your companion |
125
+ | `gitgotchi uninstall` | Remove the hook |
126
+
127
+ ## 🌕 Evolution
128
+
129
+ | Form | How to get there |
130
+ | --- | --- |
131
+ | 🎃 **Pumpkin** | Where everyone starts |
132
+ | 👻 **Ghost** | 3 commits |
133
+ | 😇 **Angel** | 6+ commits with quality above 70 |
134
+ | 😈 **Demon** | 6+ commits with quality below 30 |
135
+ | 👾 **Poltergeist** | 6+ commits, at least half by AI agents |
136
+ | 🧟 **Zombie** | 4+ reverts |
137
+ | 🌙 **Wraith** | 15+ commits |
138
+
139
+ Quality drifts toward the score of each commit:
140
+
141
+ | Factor | Points |
142
+ | --- | --- |
143
+ | Descriptive message | +15 |
144
+ | Conventional commit prefix (`feat:`, `fix:` ...) | +5 |
145
+ | Touches tests | +10 |
146
+ | Reasonable size | +5 |
147
+ | Vague message (`fix`, `wip`, `update code`) | -30 |
148
+ | Huge commit (>500 lines) | -15 |
149
+ | Revert | -10 |
150
+
151
+ Go a day without committing and your companion gets hungry; after a week it goes dormant.
152
+
153
+ ## 🖥️ Terminals
154
+
155
+ GitGotchi draws with true-color half-block characters, so it works in practically every modern terminal,
156
+ including VS Code, iTerm2, Kitty, WezTerm, Ghostty, Windows Terminal and macOS Terminal. `gitgotchi card`
157
+ also shows the image inline in terminals that support it. Set `GITGOTCHI_GRAPHICS=blocks` to turn that off.
158
+
159
+ ## 🗂️ Where state lives
160
+
161
+ Your companion is stored in `.gitgotchi/state.db` at the root of the repository. GitGotchi adds
162
+ `.gitgotchi/` to `.git/info/exclude`, so it never shows up in `git status` and is never committed.
163
+
164
+ ## 🛠️ Development
165
+
166
+ ```bash
167
+ git clone https://github.com/Srikarmk/Gitgotchi.git
168
+ cd Gitgotchi
169
+ pip install -e ".[dev]"
170
+ pytest
171
+ python scripts/render_assets.py # regenerate the images in docs/
172
+ ```
173
+
174
+ See [INSTALL.md](INSTALL.md) for more and [CHANGELOG.md](CHANGELOG.md) for release notes.
175
+
176
+ ## License
177
+
178
+ MIT - see [LICENSE](LICENSE).
@@ -0,0 +1,137 @@
1
+ # 🎃 GitGotchi
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/gitgotchi)](https://pypi.org/project/gitgotchi/)
4
+ [![CI](https://github.com/Srikarmk/Gitgotchi/actions/workflows/ci.yml/badge.svg)](https://github.com/Srikarmk/Gitgotchi/actions/workflows/ci.yml)
5
+ [![Python](https://img.shields.io/pypi/pyversions/gitgotchi)](https://pypi.org/project/gitgotchi/)
6
+
7
+ **Your terminal is haunted now.** These days AI agents write a lot of the commits, and GitGotchi is the
8
+ little spirit that lives in your repo and watches them land. Feed it commits, keep it company while
9
+ your agent works, and see what it grows into.
10
+
11
+ ![All seven forms](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/forms.png)
12
+
13
+ Every form is a real 3D model, raymarched and cel-shaded into pixel art right in your terminal.
14
+
15
+ ## 🚀 Try it
16
+
17
+ ```bash
18
+ pip install gitgotchi
19
+ gitgotchi demo
20
+ ```
21
+
22
+ `demo` opens a throwaway repo where you, Claude and Copilot take turns committing, so you can watch a
23
+ pumpkin grow into a Poltergeist in about thirty seconds.
24
+
25
+ ## 🌱 Haunt your own repo
26
+
27
+ ```bash
28
+ cd your-project
29
+ gitgotchi install # every commit now feeds your companion
30
+ gitgotchi adopt # raise it on the history you already have
31
+ gitgotchi haunt # open the live pane
32
+ ```
33
+
34
+ Keep `gitgotchi haunt` open in a split next to the terminal where you or your agent are working. Every
35
+ commit gets a reaction, agent commits glitch the screen, and evolutions play out live.
36
+
37
+ ![The haunt pane reacting to commits](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/haunt.gif)
38
+
39
+ ## 👾 Possession
40
+
41
+ GitGotchi spots commits written by AI agents (Claude, Copilot, Codex, Cursor, Devin, Aider, Gemini,
42
+ Windsurf, Cline, Amp) from their `Co-Authored-By` trailers, "Generated with" footers and bot accounts.
43
+ They feed your companion like any other commit, and they also fill its **possession** meter. Once agents
44
+ have written at least half of 6+ commits, your companion becomes a **Poltergeist**.
45
+
46
+ When git isn't attached to a terminal (an agent running `git commit`, for example), the hook prints a
47
+ single line instead of the full pet, so it doesn't flood the agent's context.
48
+
49
+ ## 🖼️ Share it
50
+
51
+ ```bash
52
+ gitgotchi card
53
+ ```
54
+
55
+ Saves a 1200×630 card, sized for LinkedIn and other link previews:
56
+
57
+ ![A sample card](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/card.png)
58
+
59
+ ## 🔮 Séance
60
+
61
+ ```bash
62
+ gitgotchi seance
63
+ ```
64
+
65
+ Your companion digs through the history for its ghosts: the oldest TODO still in the code, the file
66
+ nobody has opened in ages, the biggest deletion, commits made between midnight and 4am, and the first
67
+ commit an AI agent wrote. Then it tells you a story about them. Set `ANTHROPIC_API_KEY` (or put it in a
68
+ `.env` file) to have Claude tell it; otherwise your companion tells it in its own words.
69
+
70
+ ## 🎮 All commands
71
+
72
+ | Command | What it does |
73
+ | --- | --- |
74
+ | `gitgotchi demo` | Watch a throwaway repo get haunted |
75
+ | `gitgotchi install` | Add the post-commit hook (other hooks are kept) |
76
+ | `gitgotchi adopt` | Replay existing history (`--reset` to start over) |
77
+ | `gitgotchi haunt` | Live pane that reacts to every commit |
78
+ | `gitgotchi status` | Your companion and its stats |
79
+ | `gitgotchi seance` | Ghost stories from your repo's history |
80
+ | `gitgotchi card` | Save a shareable PNG |
81
+ | `gitgotchi evolve` | Evolution paths and progress |
82
+ | `gitgotchi pet` | Give it some affection |
83
+ | `gitgotchi name <name>` | Name your companion |
84
+ | `gitgotchi uninstall` | Remove the hook |
85
+
86
+ ## 🌕 Evolution
87
+
88
+ | Form | How to get there |
89
+ | --- | --- |
90
+ | 🎃 **Pumpkin** | Where everyone starts |
91
+ | 👻 **Ghost** | 3 commits |
92
+ | 😇 **Angel** | 6+ commits with quality above 70 |
93
+ | 😈 **Demon** | 6+ commits with quality below 30 |
94
+ | 👾 **Poltergeist** | 6+ commits, at least half by AI agents |
95
+ | 🧟 **Zombie** | 4+ reverts |
96
+ | 🌙 **Wraith** | 15+ commits |
97
+
98
+ Quality drifts toward the score of each commit:
99
+
100
+ | Factor | Points |
101
+ | --- | --- |
102
+ | Descriptive message | +15 |
103
+ | Conventional commit prefix (`feat:`, `fix:` ...) | +5 |
104
+ | Touches tests | +10 |
105
+ | Reasonable size | +5 |
106
+ | Vague message (`fix`, `wip`, `update code`) | -30 |
107
+ | Huge commit (>500 lines) | -15 |
108
+ | Revert | -10 |
109
+
110
+ Go a day without committing and your companion gets hungry; after a week it goes dormant.
111
+
112
+ ## 🖥️ Terminals
113
+
114
+ GitGotchi draws with true-color half-block characters, so it works in practically every modern terminal,
115
+ including VS Code, iTerm2, Kitty, WezTerm, Ghostty, Windows Terminal and macOS Terminal. `gitgotchi card`
116
+ also shows the image inline in terminals that support it. Set `GITGOTCHI_GRAPHICS=blocks` to turn that off.
117
+
118
+ ## 🗂️ Where state lives
119
+
120
+ Your companion is stored in `.gitgotchi/state.db` at the root of the repository. GitGotchi adds
121
+ `.gitgotchi/` to `.git/info/exclude`, so it never shows up in `git status` and is never committed.
122
+
123
+ ## 🛠️ Development
124
+
125
+ ```bash
126
+ git clone https://github.com/Srikarmk/Gitgotchi.git
127
+ cd Gitgotchi
128
+ pip install -e ".[dev]"
129
+ pytest
130
+ python scripts/render_assets.py # regenerate the images in docs/
131
+ ```
132
+
133
+ See [INSTALL.md](INSTALL.md) for more and [CHANGELOG.md](CHANGELOG.md) for release notes.
134
+
135
+ ## License
136
+
137
+ MIT - see [LICENSE](LICENSE).
@@ -0,0 +1,81 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "gitgotchi"
7
+ dynamic = ["version"]
8
+ description = "A 3D pixel-art Halloween spirit that haunts your git repo and reacts as you (and your AI agents) commit"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [
14
+ {name = "M K Sai Srikar", email = "Srikarmks@gmail.com"}
15
+ ]
16
+ keywords = [
17
+ "git",
18
+ "terminal",
19
+ "pet",
20
+ "companion",
21
+ "stardew-valley",
22
+ "ai",
23
+ "tamagotchi",
24
+ "devtools",
25
+ "halloween"
26
+ ]
27
+ classifiers = [
28
+ "Development Status :: 4 - Beta",
29
+ "Environment :: Console",
30
+ "Intended Audience :: Developers",
31
+ "Operating System :: OS Independent",
32
+ "Topic :: Software Development :: Version Control :: Git",
33
+ "Topic :: Games/Entertainment :: Simulation",
34
+ "Programming Language :: Python :: 3",
35
+ "Programming Language :: Python :: 3.10",
36
+ "Programming Language :: Python :: 3.11",
37
+ "Programming Language :: Python :: 3.12",
38
+ "Programming Language :: Python :: 3.13",
39
+ "Programming Language :: Python :: 3.14",
40
+ ]
41
+
42
+ dependencies = [
43
+ "rich>=13.7.0",
44
+ "gitpython>=3.1.40",
45
+ "anthropic>=1.0.0",
46
+ "sqlalchemy>=2.0.36",
47
+ "typer>=0.12.0",
48
+ "python-dotenv>=1.0.0",
49
+ "numpy>=1.24",
50
+ ]
51
+
52
+ [project.optional-dependencies]
53
+ dev = [
54
+ "pytest>=8.0",
55
+ "pytest-cov>=5.0",
56
+ "build>=1.2",
57
+ "ruff>=0.6",
58
+ "pillow>=10.0",
59
+ ]
60
+
61
+ [project.scripts]
62
+ gitgotchi = "gitgotchi.cli:cli"
63
+
64
+ [project.urls]
65
+ Homepage = "https://github.com/Srikarmk/Gitgotchi"
66
+ Repository = "https://github.com/Srikarmk/Gitgotchi"
67
+ Issues = "https://github.com/Srikarmk/Gitgotchi/issues"
68
+ Changelog = "https://github.com/Srikarmk/Gitgotchi/blob/main/CHANGELOG.md"
69
+
70
+ [tool.setuptools.dynamic]
71
+ version = {attr = "gitgotchi.__version__"}
72
+
73
+ [tool.setuptools.packages.find]
74
+ where = ["src"]
75
+
76
+ [tool.ruff]
77
+ line-length = 88
78
+ target-version = "py310"
79
+
80
+ [tool.pytest.ini_options]
81
+ testpaths = ["tests"]
@@ -1,4 +1,4 @@
1
- [egg_info]
2
- tag_build =
3
- tag_date = 0
4
-
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """GitGotchi - A Halloween-inspired terminal companion for your git repository."""
2
+
3
+ __version__ = "0.3.0"
@@ -0,0 +1,5 @@
1
+ """Allow running as `python -m gitgotchi`."""
2
+ from gitgotchi.cli import cli
3
+
4
+ if __name__ == "__main__":
5
+ cli()