gitgotchi 0.3.0__tar.gz → 0.4.0__tar.gz

gitgotchi-0.4.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+## 0.4.0
+
+### New
+
+- `gitgotchi-statusline`: one line about your companion for Claude Code's status line, tmux or
+  Starship. It uses only the standard library, so it runs in about 50 ms, and prints nothing outside
+  a haunted repo. `gitgotchi statusline --setup` shows the config snippets.
+- `gitgotchi badge`: an SVG README badge with a pixel portrait of your companion and its form.
+- `gitgotchi config full|line|off [--global]`: choose how much the hook prints after each commit.
+- `gitgotchi doctor`: checks git, the hook and its Python, the database, your terminal and the
+  API key, with a fix for each problem. It never prints the key.
+- `gitgotchi card --gif`: an animated card (install `gitgotchi[gif]` for Pillow).
+
+## 0.3.2
+
+### Sharper sprites
+
+- Every form is framed bigger, so it gets about 60% more pixels in the same space.
+- Shading uses hue-shifted color ramps (cool shadows, warm highlights) lit from the upper front, with
+  soft contact shadows, so forms look round instead of striped.
+- Glossy highlights on the pumpkin, the Demon and the Poltergeist's keycaps.
+- Outlines pick up a little of the color they border, and dark inner lines separate parts that
+  overlap (arms, horns, keycaps).
+- A cleanup pass removes one-pixel spurs, notches and stray shading pixels.
+- The pumpkin's shadows are warm instead of muddy, the Demon has bigger curved horns, and the Angel
+  has feathered wings and a halo that stays in frame.
+
+## 0.3.1
+
+### Fixed
+
+- **Security:** GitGotchi loaded every variable from a repo's `.env` file, so a cloned repo could
+  inject git settings and run commands during `gitgotchi seance`. Now only `ANTHROPIC_API_KEY` is read.
+- AI-agent detection no longer flags people: co-authors at Anthropic, OpenAI or Gemini, anyone named
+  Cline, or messages that merely mention ChatGPT. It now matches agent noreply addresses and bot accounts.
+- The pet now lives in `.git/gitgotchi/`, so every worktree of a repo shares one pet (agents often
+  commit from worktrees). Existing pets are moved there automatically.
+- `haunt` watches every local branch, doesn't feed commits that arrive by pull, groups bursts of
+  commits into one reaction, keeps running through a busy database, and no longer crashes on
+  brackets in commit messages.
+- Amending a commit no longer counts it again.
+- Running `adopt` while a commit is being processed could lose an update; writes are now atomic.
+- `adopt` on an existing pet no longer puts it to sleep.
+- The séance handles non-ASCII file names, renamed files, and more TODOs in big repos; the
+  witching hour uses each author's own timezone.
+- Petting a dormant pet now really wakes it, and friendship grows even while it sleeps.
+- The hook works when Python's path contains spaces or shell characters, runs before any `exit` in
+  an existing hook, and refuses to edit non-shell hooks.
+- Repos in folders with `?` or `%` in their path work.
+- `gitgotchi name` rejects empty and very long names; `card` reports the size it actually saved;
+  `adopt --limit` must be at least 1.
+- Requires `typer>=0.15.4`: older versions crash with current `click`.
+
+## 0.3.0 - Halloween
+
+### New
+
+- **3D pixel-art companion.** Every form is a 3D model, raymarched and cel-shaded into pixel art and
+  drawn in the terminal with true-color half blocks. It bobs, blinks and spins, on a night-sky stage.
+- **Halloween all year.** Pumpkin replaces Egg, and everything got a new look and voice: cute early
+  forms, eerie Demon, Wraith and Poltergeist.
+- **Possession.** Commits written by AI agents are recognised from their trailers, footers and bot
+  accounts. They fill a possession meter and unlock the new **Poltergeist** form.
+- `gitgotchi haunt`: a live pane that reacts to every commit as it lands, with sparkles, possession
+  glitches for agent commits, and evolution animations.
+- `gitgotchi adopt`: raise your companion on the history a repo already has.
+- `gitgotchi card`: a shareable 1200x630 PNG.
+- `gitgotchi seance`: ghost stories built from your repo's real history (oldest TODO, forgotten files,
+  biggest deletion, late-night commits, the first agent commit). `story` still works as an alias.
+- `gitgotchi demo`: watch a throwaway repo get haunted.
+
+### Changed
+
+- The hook prints a single line when git isn't attached to a terminal, so agents running `git commit`
+  don't get the full pet in their output.
+- Evolution plays an animation in real terminals.
+- `numpy` is now a dependency.
+- Databases from 0.2.0 are upgraded automatically.
+
+## 0.2.0
+
+### Fixed
+
+- The package is now installed as `gitgotchi` instead of `src`. The old name collided with any
+  project that has its own `src/` package and made the post-commit hook fail there.
+- `gitgotchi uninstall` now really removes the hook (it used to leave the command behind).
+- Running a command from a subdirectory no longer creates a second, empty companion.
+- `.gitgotchi/` is excluded from git automatically so the database can't be committed by accident.
+- Mood now reflects how long it's been since the last commit when you check on your companion.
+- Angel was unreachable; quality is now scored from each commit (see README).
+- `gitgotchi story` uses a current Claude model and shows why when it falls back to a built-in story.
+- `.env` files are actually loaded.
+- `gitgotchi version` reports the real version.
+
+### Changed
+
+- Hooks respect `core.hooksPath` and git worktrees, and are kept alongside any existing hook.
+  Running `gitgotchi install` again updates an old hook in place.
+- Requires `anthropic>=1.0` and `typer>=0.12`.
+- Added `python -m gitgotchi`.
+
+## 0.1.3
+
+- PyPI README update.
+
+## 0.1.0 - 0.1.2
+
+- Initial release.

{gitgotchi-0.3.0 → gitgotchi-0.4.0}/MANIFEST.in

@@ -7,3 +7,4 @@ global-exclude __pycache__
 global-exclude *.py[co]
 prune docs
 prune previews
+prune site

{gitgotchi-0.3.0 → gitgotchi-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitgotchi
-Version: 0.3.0
+Version: 0.4.0
 Summary: A 3D pixel-art Halloween spirit that haunts your git repo and reacts as you (and your AI agents) commit
 Author-email: M K Sai Srikar <Srikarmks@gmail.com>
 License-Expression: MIT
@@ -28,9 +28,11 @@ Requires-Dist: rich>=13.7.0
 Requires-Dist: gitpython>=3.1.40
 Requires-Dist: anthropic>=1.0.0
 Requires-Dist: sqlalchemy>=2.0.36
-Requires-Dist: typer>=0.12.0
+Requires-Dist: typer>=0.15.4
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: numpy>=1.24
+Provides-Extra: gif
+Requires-Dist: pillow>=10.0; extra == "gif"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
@@ -73,7 +75,9 @@ 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.
+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.
 
 ![The haunt pane reacting to commits](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/haunt.gif)
 
@@ -93,10 +97,55 @@ single line instead of the full pet, so it doesn't flood the agent's context.
 gitgotchi card
 ```
 
-Saves a 1200×630 card, sized for LinkedIn and other link previews:
+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]"`).
 
 ![A sample card](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/card.png)
 
+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`
+
+```json
+"statusLine": {"type": "command", "command": "gitgotchi-statusline"}
+```
+
+tmux: add this to `~/.tmux.conf`
+
+```bash
+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
+
+```bash
+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?
+
+```bash
+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
 
 ```bash
@@ -106,7 +155,9 @@ 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.
+`.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
 
@@ -118,7 +169,11 @@ commit an AI agent wrote. Then it tells you a story about them. Set `ANTHROPIC_A
 | `gitgotchi haunt` | Live pane that reacts to every commit |
 | `gitgotchi status` | Your companion and its stats |
 | `gitgotchi seance` | Ghost stories from your repo's history |
-| `gitgotchi card` | Save a shareable PNG |
+| `gitgotchi card` | Save a shareable card (`--gif` for an animated one) |
+| `gitgotchi badge` | Save a README badge with your companion's portrait |
+| `gitgotchi-statusline` | One line for Claude Code, tmux or Starship |
+| `gitgotchi config` | How much the hook prints: `full`, `line` or `off` |
+| `gitgotchi doctor` | Check your setup and get fixes |
 | `gitgotchi evolve` | Evolution paths and progress |
 | `gitgotchi pet` | Give it some affection |
 | `gitgotchi name <name>` | Name your companion |
@@ -158,8 +213,9 @@ also shows the image inline in terminals that support it. Set `GITGOTCHI_GRAPHIC
 
 ## 🗂️ Where state lives
 
-Your companion is stored in `.gitgotchi/state.db` at the root of the repository. GitGotchi adds
-`.gitgotchi/` to `.git/info/exclude`, so it never shows up in `git status` and is never committed.
+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
 

{gitgotchi-0.3.0 → gitgotchi-0.4.0}/README.md

@@ -32,7 +32,9 @@ 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.
+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.
 
 ![The haunt pane reacting to commits](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/haunt.gif)
 
@@ -52,10 +54,55 @@ single line instead of the full pet, so it doesn't flood the agent's context.
 gitgotchi card
 ```
 
-Saves a 1200×630 card, sized for LinkedIn and other link previews:
+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]"`).
 
 ![A sample card](https://raw.githubusercontent.com/Srikarmk/Gitgotchi/main/docs/card.png)
 
+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`
+
+```json
+"statusLine": {"type": "command", "command": "gitgotchi-statusline"}
+```
+
+tmux: add this to `~/.tmux.conf`
+
+```bash
+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
+
+```bash
+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?
+
+```bash
+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
 
 ```bash
@@ -65,7 +112,9 @@ 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.
+`.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
 
@@ -77,7 +126,11 @@ commit an AI agent wrote. Then it tells you a story about them. Set `ANTHROPIC_A
 | `gitgotchi haunt` | Live pane that reacts to every commit |
 | `gitgotchi status` | Your companion and its stats |
 | `gitgotchi seance` | Ghost stories from your repo's history |
-| `gitgotchi card` | Save a shareable PNG |
+| `gitgotchi card` | Save a shareable card (`--gif` for an animated one) |
+| `gitgotchi badge` | Save a README badge with your companion's portrait |
+| `gitgotchi-statusline` | One line for Claude Code, tmux or Starship |
+| `gitgotchi config` | How much the hook prints: `full`, `line` or `off` |
+| `gitgotchi doctor` | Check your setup and get fixes |
 | `gitgotchi evolve` | Evolution paths and progress |
 | `gitgotchi pet` | Give it some affection |
 | `gitgotchi name <name>` | Name your companion |
@@ -117,8 +170,9 @@ also shows the image inline in terminals that support it. Set `GITGOTCHI_GRAPHIC
 
 ## 🗂️ Where state lives
 
-Your companion is stored in `.gitgotchi/state.db` at the root of the repository. GitGotchi adds
-`.gitgotchi/` to `.git/info/exclude`, so it never shows up in `git status` and is never committed.
+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
 

{gitgotchi-0.3.0 → gitgotchi-0.4.0}/pyproject.toml

@@ -44,12 +44,15 @@ dependencies = [
     "gitpython>=3.1.40",
     "anthropic>=1.0.0",
     "sqlalchemy>=2.0.36",
-    "typer>=0.12.0",
+    "typer>=0.15.4",
     "python-dotenv>=1.0.0",
     "numpy>=1.24",
 ]
 
 [project.optional-dependencies]
+gif = [
+    "pillow>=10.0",
+]
 dev = [
     "pytest>=8.0",
     "pytest-cov>=5.0",
@@ -60,6 +63,7 @@ dev = [
 
 [project.scripts]
 gitgotchi = "gitgotchi.cli:cli"
+gitgotchi-statusline = "gitgotchi.statusline:main"
 
 [project.urls]
 Homepage = "https://github.com/Srikarmk/Gitgotchi"

{gitgotchi-0.3.0 → gitgotchi-0.4.0}/src/gitgotchi/__init__.py

@@ -1,3 +1,3 @@
 """GitGotchi - A Halloween-inspired terminal companion for your git repository."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{gitgotchi-0.3.0 → gitgotchi-0.4.0}/src/gitgotchi/cli.py

@@ -1,10 +1,11 @@
 """Main CLI interface."""
+import os
 import random
 from pathlib import Path
 from typing import Optional
 
 import typer
-from dotenv import find_dotenv, load_dotenv
+from dotenv import dotenv_values, find_dotenv
 from rich.panel import Panel
 from rich.table import Table
 from rich.text import Text
@@ -24,10 +25,24 @@ app = typer.Typer(
 
 def cli():
     """Entry point for console script."""
-    load_dotenv(find_dotenv(usecwd=True))
+    load_api_key()
     app()
 
 
+def load_api_key() -> None:
+    """Pick up ANTHROPIC_API_KEY from a .env file if it isn't already set.
+
+    Only that one variable is read: a repo's .env could otherwise inject
+    settings such as GIT_CONFIG_* into the git commands GitGotchi runs.
+    """
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return
+    path = find_dotenv(usecwd=True)
+    key = dotenv_values(path).get("ANTHROPIC_API_KEY") if path else None
+    if key:
+        os.environ["ANTHROPIC_API_KEY"] = key
+
+
 def load_state() -> StateManager:
     try:
         return StateManager()
@@ -106,6 +121,9 @@ def pet():
         raise typer.Exit(1)
 
 
+MAX_NAME_LENGTH = 30
+
+
 @app.command()
 def name(new_name: str):
     """Give your companion a name."""
@@ -113,6 +131,11 @@ def name(new_name: str):
         state_manager = load_state()
         pet_stats = state_manager.get_pet_state()
 
+        new_name = " ".join(new_name.split())
+        if not new_name or len(new_name) > MAX_NAME_LENGTH:
+            render_error(f"Names need between 1 and {MAX_NAME_LENGTH} characters.")
+            raise typer.Exit(1)
+
         old_name = pet_stats.pet_name
         pet_stats.pet_name = new_name
         state_manager.save_pet_state(pet_stats)
@@ -245,7 +268,7 @@ def story():
 
 @app.command()
 def adopt(
-    limit: Optional[int] = typer.Option(None, help="Only replay the most recent N commits"),
+    limit: Optional[int] = typer.Option(None, min=1, help="Only replay the most recent N commits"),
     reset: bool = typer.Option(False, "--reset", help="Start the pet over before replaying"),
 ):
     """Raise your companion on this repo's existing history."""
@@ -294,30 +317,64 @@ def adopt(
 
 @app.command()
 def card(
-    output: Path = typer.Option(Path("gitgotchi-card.png"), "--output", "-o", help="Where to save the PNG"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Where to save it (default gitgotchi-card.png, or .gif with --gif)"),
     scale: int = typer.Option(5, help="Pixel size; 5 gives 1200x630"),
+    gif: bool = typer.Option(False, "--gif", help="Save an animated GIF (needs: pip install 'gitgotchi[gif]')"),
 ):
-    """Save a shareable card of your companion as a PNG."""
+    """Save a shareable card of your companion."""
     from gitgotchi.paths import require_repo
-    from gitgotchi.render.card import make_card
+    from gitgotchi.render.card import make_card, make_card_gif
     from gitgotchi.render.scene import encode_png, upscale
     from gitgotchi.render.terminal import graphics_protocol, inline_image
 
     state_manager = load_state()
     stats = state_manager.get_pet_state()
     repo_name = Path(require_repo().working_tree_dir).name
-
-    image = make_card(stats, repo_name, state_manager.agent_counts())
-    output.write_bytes(encode_png(upscale(image, max(1, min(12, scale)))))
+    agents = state_manager.agent_counts()
+    scale = max(1, min(12, scale))
+    output = output or Path("gitgotchi-card.gif" if gif else "gitgotchi-card.png")
+
+    image = make_card(stats, repo_name, agents)
+    if gif:
+        try:
+            data = make_card_gif(stats, repo_name, agents, scale=scale)
+        except ImportError:
+            render_error("Animated cards need Pillow: pip install 'gitgotchi[gif]'")
+            raise typer.Exit(1)
+        output.write_bytes(data)
+    else:
+        output.write_bytes(encode_png(upscale(image, scale)))
 
     protocol = graphics_protocol()
     if protocol and console.is_terminal:
         console.file.write(inline_image(image, min(console.width - 2, 96), protocol))
         console.file.flush()
-    console.print(Text(f"\n🖼️  Saved {output} ({image.shape[1] * scale}x{image.shape[0] * scale})", style=theme.ORANGE))
+    size = f"{image.shape[1] * scale}x{image.shape[0] * scale}"
+    console.print(Text(f"\n🖼️  Saved {output} ({size})", style=theme.ORANGE))
     console.print(Text("Share it, and tag the spirits that wrote your code.\n", style=theme.DIM))
 
 
+@app.command()
+def badge(
+    output: Path = typer.Option(Path("gitgotchi-badge.svg"), "--output", "-o", help="Where to save the SVG"),
+):
+    """Save a README badge with your companion's portrait and form."""
+    from gitgotchi.render.badge import make_badge
+
+    from gitgotchi.paths import require_repo
+
+    stats = load_state().get_pet_state()
+    output.write_text(make_badge(stats), encoding="utf-8")
+    root = Path(require_repo().working_tree_dir).resolve()
+    try:
+        link = output.resolve().relative_to(root).as_posix()
+    except ValueError:  # saved outside the repo
+        link = output.as_posix()
+    console.print(Text(f"\n🏷️  Saved {output}. Commit it and add this to your README:", style=theme.ORANGE))
+    console.print(Text(f"[![GitGotchi]({link})](https://github.com/Srikarmk/Gitgotchi)\n", style=theme.BONE))
+    console.print(Text("Run `gitgotchi badge` again whenever your companion evolves.\n", style=theme.DIM))
+
+
 @app.command()
 def haunt(fps: int = typer.Option(12, help="Frames per second")):
     """Open a live pane where your companion reacts to every commit.
@@ -348,6 +405,86 @@ def demo():
     console.print(Text("🎃 That's GitGotchi. Run `gitgotchi install` in a real repo to adopt your own.", style=theme.ORANGE))
 
 
+@app.command()
+def config(
+    output: Optional[str] = typer.Argument(None, help="full, line or off"),
+    global_: bool = typer.Option(False, "--global", help="Set it for every repo instead of this one"),
+):
+    """Choose how much the hook prints after each commit.
+
+    full: the whole pet (default). line: one line. off: nothing.
+    Stored in git config as gitgotchi.output.
+    """
+    from gitgotchi.hooks.post_commit import configured_output
+    from gitgotchi.paths import find_repo
+    from gitgotchi.pet.renderer import OUTPUT_STYLES
+
+    repo = find_repo()
+    if output is None:
+        if repo is None:
+            render_error("No git repository found here. Run `git init` first.")
+            raise typer.Exit(1)
+        console.print(Text(f"gitgotchi.output = {configured_output(repo)}", style=theme.ORANGE))
+        return
+
+    output = output.strip().lower()
+    if output not in OUTPUT_STYLES:
+        render_error(f"Pick one of: {', '.join(OUTPUT_STYLES)}")
+        raise typer.Exit(1)
+    if not global_ and repo is None:
+        render_error("No git repository here. Use --global to set it everywhere.")
+        raise typer.Exit(1)
+
+    if global_:
+        from git import Git
+
+        Git().config("--global", "gitgotchi.output", output)
+    else:
+        repo.git.config("gitgotchi.output", output)
+    where = "every repo" if global_ else "this repo"
+    console.print(Text(f"🕯️  Hook output set to {output} for {where}.", style=theme.ORANGE))
+
+
+@app.command()
+def doctor():
+    """Check your setup and explain how to fix anything that's wrong."""
+    from gitgotchi.doctor import FAIL, WARN, run_checks
+
+    checks = run_checks(console)
+    marks = {"ok": ("✓", theme.GREEN), WARN: ("!", theme.ORANGE), FAIL: ("✗", theme.BLOOD)}
+    table = Table.grid(padding=(0, 2))
+    table.add_column(no_wrap=True)
+    table.add_column(no_wrap=True, style="bold")
+    table.add_column()
+    for check in checks:
+        mark, color = marks[check.status]
+        detail = Text(check.detail, overflow="fold")
+        if check.fix and check.status != "ok":
+            detail.append(f"\n→ {check.fix}", style=color)
+        table.add_row(Text(mark, style=f"bold {color}"), check.name, detail)
+    console.print(Panel(table, title="🩺 GitGotchi doctor", border_style=theme.PURPLE, expand=False))
+
+    failures = [c for c in checks if c.status == FAIL]
+    if failures:
+        console.print(Text(f"{len(failures)} problem{'s' if len(failures) > 1 else ''} to fix.", style=theme.BLOOD))
+        raise typer.Exit(1)
+    console.print(Text("Everything needed is working.", style=theme.GREEN))
+
+
+@app.command()
+def statusline(
+    plain: bool = typer.Option(False, "--plain", help="No colors (for tmux or Starship)"),
+    setup: bool = typer.Option(False, "--setup", help="Show how to add it to Claude Code, tmux and Starship"),
+):
+    """Print one line about your companion, for status bars and prompts.
+
+    For status bars, use the faster `gitgotchi-statusline` command instead.
+    """
+    from gitgotchi.statusline import main
+
+    raise typer.Exit(main((["--plain"] if plain else []) + (["--setup"] if setup else [])))
+
+
 @app.command()
 def version():
     """Show GitGotchi version."""