Codigatchi

A terminal-native, local-first coding companion. Codigatchi is a pet that grows from your real coding accomplishments — observed through your agent CLI's lifecycle hooks (Claude Code is first-class) plus a lightweight zsh hook. It never sees your code or your prompts: only signals.

Signals, not surveillance

Codigatchi only ever records:

• the category of a bash command (commit, push, tag, test, build, install, run)
• diff line counts (insertions/deletions, not content)
• commit titles (the one-line summary, nothing else)
• time of day

It never records file contents, prompt text, diffs, or command output. Nothing leaves your machine.

Local-first, by construction

Some coding companions POST your activity to a cloud leaderboard and turn your work into a social feed. Codigatchi is the opposite: fully offline, private by construction, and it lives entirely in your terminal. There is no server, no account, and no leaderboard. What happens in your shell stays in your shell.

Install & quickstart

npm install -g codigatchi

(or from source: npm install && npm run build, then npm link)

Hatch your pet:

codigatchi hatch

This runs a short ceremony: a quiz, a choice of 1 of 3 starter eggs, and a tone for your pet.

Wire up the hooks:

codigatchi install

Prints a diff of what it's about to change before touching anything, and is fully reversible with codigatchi uninstall.

Summon your pet:

codigatchi

A live full-screen view that updates in real time as you work — leave it open in a split pane. Press p to pet it, q to quit.

Check status from your shell prompt:

codigatchi status

Prints a one-liner suitable for embedding in PS1/RPROMPT or a starship-style segment.

Concept

Every pet has a surface affinity — one of Scribe, Terse, Sage, Hunter, Architect, or Sprint — assigned during the hatch quiz. This is the pet's visible personality.

Underneath, every pet also accrues one of six hidden elements: Fire, Water, Earth, Air, Lightning, or Aether. These are never shown as a stat or number — they build up silently from how you actually code, and only surface through flavor text and branching at the stage-2 evolution. The element line continues to its final form at stage 3.

XP is deliberately anti-gaming:

• category-weighted (a commit isn't worth the same as a keystroke)
• diminishing returns on repeated identical actions
• shipping (commits, tags, passing tests) counts far more than raw activity — a good commit title and a substantial diff pay more than five "wip" commits in ten minutes

Optional: bring your own model

Everything works fully offline with scripted dialogue. Configuring an LLM backend lights up two extras — both strictly opt-in:

• Local (recommended): CODIGATCHI_LLM=ollama uses a featherweight Gemma via Ollama (gemma4:e2b by default; pick another with CODIGATCHI_LLM=ollama/<model>). Nothing ever leaves your machine.
• Local, any runtime: CODIGATCHI_LLM=openai/<model> talks to any OpenAI-compatible server — mlx_lm.server (MLX on Apple Silicon), LM Studio, vLLM, llamafile. Endpoint defaults to http://127.0.0.1:8080/v1; override with CODIGATCHI_OPENAI_URL (LM Studio: http://127.0.0.1:1234/v1).
• Hosted: CODIGATCHI_API_KEY (an Anthropic API key) uses a frontier model instead. CODIGATCHI_LLM wins if both are set.

What they enable:

• Comprehension quiz — codigatchi quiz reads your latest commit's diff and quizzes you on what actually changed; correct answers earn bonus XP — proof you really reviewed what shipped, not just approved it. With the hosted backend it asks per-run consent before sending the diff; with Ollama it never needs to, because nothing leaves the machine.
• LLM dialogue — your pet speaks in its own generated voice (affinity, tone, and life stage only — never your code or prompts).

Roadmap

Scaffolded, not yet load-bearing:

• a tmux / cmux status segment
• more agent CLI adapters beyond Claude Code (codex/gemini scaffolds exist)
• stage 4+ evolutions