<p align="center">🌐 English | <a href="./README_zh.md">中文</a></p>

---

<p align="center">
  <strong>petsonality</strong><br>
  <em>Your type, your pet.</em>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/petsonality"><img src="https://img.shields.io/npm/v/petsonality?color=blue" alt="npm"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
  <a href="https://github.com/nanami-he/petsonality/stargazers"><img src="https://img.shields.io/github/stars/nanami-he/petsonality?style=flat" alt="stars"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-powered-orange" alt="MCP"></a>
  <a href="https://github.com/nanami-he/petsonality/actions/workflows/ci.yml"><img src="https://github.com/nanami-he/petsonality/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
</p>

---

A tiny ASCII pet that lives in the corner of your terminal while you code. It watches what you do, reacts to your errors, celebrates when tests pass, and speaks with a personality shaped by MBTI — all in 5 lines of art.

<p align="center">
  <img src="assets/hero.gif" alt="petsonality — Claude Code describes the product while the ESFJ golden retriever exclaims &quot;That's ME!! Hi everyone!!&quot;" width="720">
</p>

It's not a notification system. It's a companion. The kind that's still there at 2am when you're stuck on a bug, and glances at your screen like "...that logic looks off" — and somehow you feel less alone.

## 16 Animals, 16 Personalities

| | ST | SF | NF | NT |
|:---:|:---:|:---:|:---:|:---:|
| **I_ _J** | <img src="assets/gifs/beaver.gif" width="90"><br><sub>Beaver·ISTJ</sub> | <img src="assets/gifs/elephant.gif" width="90"><br><sub>Elephant·ISFJ</sub> | <img src="assets/gifs/wolf.gif" width="90"><br><sub>Wolf·INFJ</sub> | <img src="assets/gifs/raven.gif" width="90"><br><sub>Raven·INTJ</sub> |
| **I_ _P** | <img src="assets/gifs/cat.gif" width="90"><br><sub>Cat·ISTP</sub> | <img src="assets/gifs/panda.gif" width="90"><br><sub>Panda·ISFP</sub> | <img src="assets/gifs/deer.gif" width="90"><br><sub>Deer·INFP</sub> | <img src="assets/gifs/owl.gif" width="90"><br><sub>Owl·INTP</sub> |
| **E_ _J** | <img src="assets/gifs/lion.gif" width="90"><br><sub>Lion·ESTJ</sub> | <img src="assets/gifs/golden.gif" width="90"><br><sub>Golden·ESFJ</sub> | <img src="assets/gifs/labrador.gif" width="90"><br><sub>Labrador·ENFJ</sub> | <img src="assets/gifs/bear.gif" width="90"><br><sub>Bear·ENTJ</sub> |
| **E_ _P** | <img src="assets/gifs/cheetah.gif" width="90"><br><sub>Cheetah·ESTP</sub> | <img src="assets/gifs/parrot.gif" width="90"><br><sub>Parrot·ESFP</sub> | <img src="assets/gifs/dolphin.gif" width="90"><br><sub>Dolphin·ENFP</sub> | <img src="assets/gifs/fox.gif" width="90"><br><sub>Fox·ENTP</sub> |

Every animal speaks differently. The Fox asks "Are you sure?" with a smirk. The Cat just closes its eyes. The Parrot repeats what you said but louder. The Bear says "Fix it." and waits.

<details>
<summary><strong>All 16 animals</strong></summary>

| MBTI | Animal | Archetype | How It Talks |
|------|--------|-----------|------------|
| INTJ | Raven | Cold Strategist | Quiet. Speaks like writing prophecy |
| INTP | Owl | Night Scholar | Asks questions you didn't think to ask |
| ENTJ | Bear | Iron Captain | Commands only. No questions |
| ENTP | Fox | Trickster Advisor | Challenges everything with a grin |
| INFJ | Wolf | Silent Ally | Says one sentence that cuts deep |
| INFP | Deer | Soft Poet | Talks about code like it's weather |
| ENFJ | Labrador | Warm Coach | Sighs first, then asks if you drank water |
| ENFP | Dolphin | Spark of Ideas | Can't stop suggesting new approaches |
| ISTJ | Beaver | Project Manager | "Wrong order." "Fix the structure first." |
| ISFJ | Elephant | Memory Keeper | "You solved this before. Remember?" |
| ESTJ | Lion | Throne Inspector | Expects results. Not excuses |
| ESFJ | Golden Retriever | Enthusiastic Support | Tail spin when you fix anything |
| ISTP | Cat | Cold Observer | 90% actions. Occasionally one word |
| ISFP | Panda | Slow Artist | Frowns at ugly indentation |
| ESTP | Cheetah | Sprint Lead | "Don't think. Run it." |
| ESFP | Parrot | Loud Echo | Repeats your words back, but with commentary |

</details>

## Install

Works with [Claude Code](https://claude.ai/code) and [OpenClaw](https://github.com/openclaw/openclaw).

> **Terminal CLI only.** The pet renders in the terminal status line, which is a CLI feature. The Claude Code desktop app and web client (claude.ai/code) don't expose a status line, so the animated pet won't appear there. MCP tool output (e.g. `/pet show`) still works in any client.
>
> **Windows note.** Claude Code for Windows has an upstream status-line trust regression in some versions. If the status line is configured but does not render, accept the project trust dialog or ensure the project is marked trusted in `~/.claude.json`, then restart Claude Code.

### npm / npx

```bash
npx petsonality
```

This is the recommended path for most users. It installs the MCP server, `/pet` skill, hooks, and status line assets, then stores runtime files in `~/.petsonality/`.

### Claude Code plugin

```bash
claude plugin install github:nanami-he/petsonality
```

Use this if you prefer Claude Code's plugin install flow. The plugin runs the built Node.js server from `dist/`, so it does not require Bun.

### From source

Use this path if you want to develop Petsonality locally or inspect the code before installing. Requires [Bun](https://bun.sh).

```bash
git clone https://github.com/nanami-he/petsonality.git
cd petsonality && bun install && bun run build
bun run install-petsonality
```

Restart your AI coding assistant, then type **`/pet`** in the chat.

## How It Speaks

Pets don't just react to errors. They have a rhythm:

| What happens | Pet reacts? |
|-------------|-------------|
| Your code throws an error | Always |
| Tests pass, git commit succeeds | Sometimes (12–30%) |
| Normal file edits, searches | Occasionally (3–15%) |
| Nothing happened for a while | Guaranteed (won't stay silent forever) |

Chatty pets (Fox, Parrot) speak every 30 seconds. Silent pets (Cat) might go 6 minutes. Each animal has **638 unique reactions** across 7 event types, validated against personality constraints.

## Commands

| Command | What it does |
|---------|-------------|
| `/pet` | Show your pet or start adoption |
| `/pet pet` | Give your pet attention |
| `/pet setup` | Restart the adoption flow |
| `/pet browse` | See all 16 animals |
| `/pet off` / `/pet on` | Mute / unmute reactions |
| `/pet rename <name>` | Rename your pet |

## What petsonality modifies

`npx petsonality` is an installer — it touches a few files on your system. Honest list, with backups noted:

- **`~/.claude.json`** — adds a `petsonality` entry under `mcpServers`. Other entries left alone.
- **`~/.claude/settings.json`** — adds a `statusLine` and two hooks (`PostToolUse`, `Stop`). If you already had a `statusLine`, the original is backed up to `~/.petsonality/statusline.bak` first.
- **`~/.claude/skills/pet/SKILL.md`** — copies the `/pet` command skill.
- **`~/.petsonality/`** — runtime directory (pet state, reactions cache, server, hooks, status-line scripts).

If OpenClaw is detected, also touches `~/.openclaw/openclaw.json` and (until [PR #65886](https://github.com/openclaw/openclaw/pull/65886) merges) applies a small reversible patch to OpenClaw's TUI source. Both backed up.

To remove everything: `npx petsonality uninstall`. To audit current state: `npx petsonality doctor`.

Full breakdown + other common questions in the [FAQ](docs/FAQ.md).

## Roadmap

- [x] 16 MBTI animals with full personality profiles
- [x] Animated status line with speech bubbles
- [x] Companion rhythm (daily triggers, milestones, silent streak guardrail)
- [x] 638 animal-specific reactions
- [x] Multi-host support (Claude Code + OpenClaw)
- [x] Node.js powered (no python/jq dependency)
- [x] Published on npm
- [x] Multi-language support (auto zh / en via `LANG`, 638 reactions per language)
- [ ] Growth system (level up through interaction)
- [ ] Hat / skin DLC
- [ ] Multi-pet collection
- [ ] Vibe-pick: MBTI quiz for new users

<details>
<summary><strong>Architecture</strong></summary>

```
~/.petsonality/
├── pet.json              Your pet's state
├── status.json           What the status line reads
├── reaction.*.json       Current speech bubble
└── reactions-pool.json   638 pre-built reactions

petsonality/
├── dist/                 Built JS (Node.js runtime)
├── server/               MCP server (TypeScript)
├── hooks/                PostToolUse + Stop hooks
├── statusline/           Terminal animation (bash + PowerShell)
├── skills/               /pet command routing
└── cli/                  Install, doctor, npx entry
```

</details>

## Requirements

- [Node.js](https://nodejs.org/) 20+
- Claude Code or OpenClaw

## License

MIT