ani-mime

KO | EN

gitlite — search

#python #hacktoberfest #go #android #machine-learning #rust #deep-learning #linux #java #windows #awesome #kubernetes #pytorch #open-source

(★ 26)

Floating macOS status pill that tracks terminal & Claude Code activity

ani-mime 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Ani-Mime

A floating pixel mascot that mirrors your terminal & Claude Code activity on macOS and Linux.

---

## What is Ani-Mime?

A tiny always-on-top pixel dog that reacts to what your terminal is doing. It sniffs when you're building, barks when a dev server is running, sits when you're free, and sleeps when nothing's happening.

It also integrates with **Claude Code** — the dog knows when Claude is thinking vs waiting for you.

## Contributors

Ani-Mime wouldn't be the same without these wonderful people. Thank you for your time, ideas, and code — you made this project better.

<table>
 <tr>
 <td align="center">
 <a href="https://github.com/thnh-dng">
 <img src="https://avatars.githubusercontent.com/u/213000297?v=4" width="80" height="80" alt="thnh-dng" />
 
 thnh-dng
 </a>
 </td>
 <td align="center">
 <a href="https://github.com/yanmad27">
 <img src="https://avatars.githubusercontent.com/u/38394675?v=4" width="80" height="80" alt="yanmad27" />
 
 yanmad27
 </a>
 </td>
 <td align="center">
 <a href="https://github.com/thanh-dong">
 <img src="https://avatars.githubusercontent.com/u/15724923?v=4" width="80" height="80" alt="thanh-dong" />
 
 thanh-dong
 </a>
 </td>
 <td align="center">
 <a href="https://github.com/setnsail">
 <img src="https://avatars.githubusercontent.com/u/213003653?v=4" width="80" height="80" alt="setnsail" />
 
 setnsail
 </a>
 </td>
 <td align="center">
 <a href="https://github.com/QuangHo0911">
 <img src="https://avatars.githubusercontent.com/u/207322672?v=4" width="80" height="80" alt="QuangHo0911" />
 
 QuangHo0911
 </a>
 </td>
 <td align="center">
 <a href="https://github.com/cuongtranba">
 <img src="https://avatars.githubusercontent.com/u/4550606?v=4" width="80" height="80" alt="cuongtranba" />
 
 cuongtranba
 </a>
 </td>
 </tr>
</table>

## Mascot States

## Features

- **Pixel Art Mascot** — animated sprite sheet dog above the status pill
- **Custom Sprites** — upload your own PNG sprite sheets via manual import or smart extraction with chroma-key background removal
- **Frame Range Expressions** — specify frames as ranges like `1-5` or `41-55,57,58` when importing custom sprites
- **Display Scale** — resize your mascot with Tiny / Normal / Large / XL presets
- **Peer Visits** — discover other Ani-Mime users on your local network via Bonjour/mDNS; right-click to send your pet to visit theirs
- **Manual Tagging** — zsh hooks classify commands as `task` or `service`
- **Heartbeat + OS Scan** — hooks drive state transitions; a 2s libproc scan auto-discovers every live shell and cleans up zombies
- **Session Dropdown** — click the status pill to see every open terminal grouped by project path, with the foreground command (`claude`, `bun`, etc.), and click any row to jump straight to that tab (see [Session List & Click-to-Focus](#session-list--click-to-focus))
- **Claude Code Hooks** — tracks when Claude is actively working vs waiting
- **Claude Code Management UI** — view and manage your Claude Code configuration from Settings → Claude Code: list installed plugins with enable/disable toggles, inspect global and per-project MCP servers, browse and delete custom slash commands, and review/remove hooks
- **MCP Server** — Claude Code can talk to your pet: trigger speech bubbles, play reaction animations, and check pet status via MCP tools
- **Multi-Session** — handles multiple terminals, priority: busy > service > idle
- **Auto-Setup** — first launch configures zsh hooks and Claude Code hooks via native macOS dialogs
- **All Workspaces** — visible on every macOS Space/desktop
- **Menu Bar Tray Icon** — always-visible tray icon with right-click menu; left-click toggles mascot visibility
- **Hide from Dock** — optional setting to remove the app from Dock and Cmd+Tab, running as a menu bar-only app
- **Low Footprint** — Rust + Tauri, minimal CPU and RAM

## Screenshots

<table>
 <tr>
 <td><img src="docs/assets/settings-general.png" alt="General settings" width="300"></td>
 <td><img src="docs/assets/settings-mime.png" alt="Customize your favorite Mime" width="300"></td>
 <td><img src="docs/assets/shadow-clone.gif" alt="Shadow Clone feature" width="300"></td>
 </tr>
 <tr>
 <td align="center">General settings</td>
 <td align="center">Customize your favorite Mime</td>
 <td align="center">Shadow Clone feature</td>
 </tr>
 <tr>
 <td><img src="docs/assets/menu-bar.png" alt="Show on macOS menu bar" width="300"></td>
 <td><img src="docs/assets/import-export.png" alt="One-click import and export of custom Mimes" width="300"></td>
 <td><img src="docs/assets/settings-claude-code.png" alt="Claude Code management UI" width="300"></td>
 </tr>
 <tr>
 <td align="center">Show on menu bar</td>
 <td align="center">One-click import &amp; export your Mime</td>
 <td align="center">Claude Code management UI</td>
 </tr>
</table>

---

## Session List & Click-to-Focus

Click the status pill to open a dropdown listing every open terminal, grouped by working directory:

**Click any row** and Ani-Mime brings that terminal to the front. For apps with scripting support it jumps to the specific tab; for the rest it just activates the app. The walk up the process tree uses `pidpath` + a `ps`-based ppid map, so it works even across root-owned ancestors like `/usr/bin/login`.

### Terminal app support matrix

| App                        | Activate | Tab-precise focus | How                                                                                               |
| -------------------------- | :------: | :---------------: | ------------------------------------------------------------------------------------------------- |
| **iTerm2**                 |    ✅    |         ✅        | AppleScript: matches the `tty` property on every session                                          |
| **Terminal.app**           |    ✅    |         ✅        | AppleScript: matches the `tty` property on every tab                                              |
| **VS Code**                |    ✅    |      ⚠️ Window    | System Events + window title contains the workspace folder name (can't target individual panes — Electron) |
| **Cursor**                 |    ✅    |      ⚠️ Window    | Same approach as VS Code                                                                          |
| **tmux** (inside any host) |    ✅    |         ✅        | `tmux select-pane -t` + `select-window` + `switch-client` matched by `pane_tty`; host app also activated |
| **Warp**                   |    ✅    |         ❌        | No public scripting API for tabs — activation only                                                |
| **WezTerm**                |    ✅    |         ❌        | Has a `wezterm cli` pane API but no pid→pane mapping from outside                                 |
| **Alacritty / kitty / Hyper / Ghostty** | ✅ | ❌         | No inter-app scripting exposed — activation only                                                  |
| **ssh session**            |    ✅    |         ❌        | Remote shells resolve to the local ssh ancestor — activate the local terminal                    |

### Permissions

The first time Ani-Mime tries to script another app, macOS will prompt:

- **iTerm / Terminal** — Automation permission. Grant once; subsequent clicks target the exact tab.
- **VS Code / Cursor** — Accessibility permission (required by System Events to raise windows). Find Ani-Mime under **System Settings → Privacy & Security → Accessibility** and enable it.

Without these permissions, the click still brings the app to the front via `open -a` (Launch Services, no permission needed) — you just lose the precise tab / window targeting.

---

## Install

### macOS — Homebrew (recommended)

```bash
brew tap vietnguyenhoangw/ani-mime
brew install --cask ani-mime
```

Open the app. On first launch, Ani-Mime will:
1. Ask to add a hook to your `~/.zshrc` (required for terminal tracking)
2. Ask to configure Claude Code hooks (optional)

Open a new terminal tab and the mascot starts reacting.

The MCP server is also auto-configured so Claude Code can interact with your pet directly (see [MCP Server](#mcp-server) below).

### Linux — `.deb`, `.rpm`, or `.AppImage`

Download the bundle for your distro and arch from the [Releases page](https://github.com/vietnguyenhoangw/ani-mime/releases/latest):

```bash
# Debian / Ubuntu
sudo apt install ./ani-mime_X.Y.Z_amd64.deb      # or _arm64.deb on ARM

# Fedora / RHEL / openSUSE
sudo rpm -i ani-mime-X.Y.Z-1.x86_64.rpm          # or .aarch64.rpm

# AppImage (any distro)
chmod +x ani-mime_X.Y.Z_amd64.AppImage && ./ani-mime_X.Y.Z_amd64.AppImage
```

Runtime deps (installed automatically by `apt`/`rpm`; required manually for AppImage):

```bash
sudo apt install libwebkit2gtk-4.1-0 libayatana-appindicator3-1 zenity xdg-utils
```

### WSL2

Install the Linux `.deb` inside your WSL2 distro. Always-on-top works via a WSLg-specific `SetWindowPos(HWND_TOPMOST)` shim — no extra setup required.

### Manual (from source)

```bash
git clone https://github.com/vietnguyenhoangw/ani-mime.git
cd ani-mime
bun install
bun tauri dev
```

On Linux you also need the build deps:

```bash
sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \
  librsvg2-dev libxdo-dev libglib2.0-dev libsoup-3.0-dev libjavascriptcoregtk-4.1-dev \
  xdg-utils pkg-config build-essential zenity
```

Then source the shell script for your shell (`terminal-mirror.zsh`, `.bash`, or `.fish`):

```bash
echo 'source "/path/to/ani-mime/src-tauri/script/terminal-mirror.zsh"' >> ~/.zshrc
source ~/.zshrc
```

---

## Requirements

- **macOS** (Intel or Apple Silicon) — full feature set
- **Linux** (x86_64 or aarch64) — runs with shell hooks; some click-to-focus integrations are macOS-only
- **WSL2 / WSLg** — runs as a Linux build with a WSLg-aware always-on-top shim
- **Shell** — zsh / bash / fish (hooks provided for each)
- **Claude Code** (optional) — for Claude activity tracking

### Platform feature matrix

| Feature                              | macOS | Linux | WSL2 |
| ------------------------------------ | :---: | :---: | :--: |
| Mascot + speech bubbles              |  ✅   |  ✅   |  ✅  |
| Shell hook tracking (zsh/bash/fish)  |  ✅   |  ✅   |  ✅  |
| Claude Code hooks + MCP server       |  ✅   |  ✅   |  ✅  |
| Always-on-top over full-screen apps  |  ✅   |  ✅   |  ✅  |
| Peer discovery (mDNS / Bonjour)      |  ✅   |  ✅   |  ⚠️  |
| Session list dropdown                |  ✅   |  ✅   |  ✅  |
| Click-to-focus terminal tabs         |  ✅   |  ❌   |  ❌  |
| Auto shell discovery (libproc scan)  |  ✅   |  ❌   |  ❌  |
| Homebrew cask install                |  ✅   |  —    |  —   |
| Auto-install update via `brew`       |  ✅   |  —    |  —   |

Linux and WSL2 fall back to the shell-hook based path for terminal tracking — you get the full mascot + Claude Code + MCP experience, just without the macOS-only auto-discovery and tab-precise focus.

## Tech Stack

- **Frontend:** React 19, TypeScript, Vite
- **Backend:** Rust, Tauri v2, tiny_http
- **Shell:** zsh hooks (preexec / precmd)
- **Sprites:** CSS sprite sheet animation (128×128 pixel art, scalable)
- **Testing:** Vitest (unit), Playwright (e2e)

---

## Testing

```bash
# Unit tests
bun run test

# E2E tests (requires dev server on :1420)
npx playwright test --config=e2e/playwright.config.ts
```

The e2e suite covers app startup, status transitions, speech bubbles, scenario mode, settings, custom sprite upload (including frame range expressions), sprite display sizing, and custom sprite editing.

---

## Peer Visits

Ani-Mime instances on the same local network automatically discover each other via mDNS (Bonjour). Right-click your mascot to see nearby peers and send your pet to visit them.

### Requirements

- Both machines on the **same WiFi / LAN subnet**
- **macOS Local Network permission** — allow when prompted on first launch (or enable in System Settings > Privacy & Security > Local Network)

### Troubleshooting

If peers can't find each other:

1. Check that both machines are on the same network (`192.168.x.x` subnet)
2. Verify Local Network permission is enabled for ani-mime on both machines
3. Run `dns-sd -B _ani-mime._tcp local.` in Terminal — you should see both instances
4. Run `curl http://127.0.0.1:1234/debug` to check the registered IP and peer list
5. If sharing the app via DMG without a Developer ID, the recipient must run:
   ```bash
   xattr -cr /Applications/ani-mime.app
   ```

See [docs/peer-discovery.md](docs/peer-discovery.md) for the full protocol reference.

---

## MCP Server

Ani-Mime includes an MCP (Model Context Protocol) server that lets Claude Code interact with your pet during conversations.

### What It Does

| Tool | Description |
|------|-------------|
| `pet_say` | Make your pet say something via a speech bubble |
| `pet_react` | Trigger a reaction animation (celebrate, nervous, confused, excited, sleep) |
| `pet_status` | Check what your pet is doing, who's visiting, nearby peers, and uptime |

### Setup

The MCP server is automatically configured during first-launch setup (when you accept Claude Code hooks). If you need to set it up manually:

```bash
claude mcp add ani-mime -- node ~/.ani-mime/mcp/server.mjs
```

The server script is updated automatically on every app launch.

### How It Works

```
Claude Code <--stdio--> MCP Server (Node.js) <--HTTP--> Ani-Mime :1234 --> Pet UI
```

Claude Code calls MCP tools during conversations. The MCP server translates them to HTTP requests to the local Ani-Mime server, which emits Tauri events to the frontend. The pet reacts with speech bubbles or animation changes.

---

## Building for Release

### macOS (DMG)

```bash
# Build the Tauri app
bun run tauri build

# Re-sign with entitlements and re-create the DMG
# (required because Tauri doesn't embed entitlements for ad-hoc signing)
bash src-tauri/script/post-build-sign.sh
```

The signed DMG is output to `src-tauri/target/release/bundle/dmg/`.

**Without the post-build sign step**, the app will run on the build machine but peer discovery (mDNS) and the HTTP server will silently fail on other machines due to missing network entitlements.

If the recipient sees "app is damaged", they need to remove the quarantine attribute:

```bash
xattr -cr /Applications/ani-mime.app
```

### Linux (`.deb`, `.rpm`, `.AppImage`)

```bash
bun run tauri build
```

Produces all three bundle formats under `src-tauri/target/release/bundle/{deb,rpm,appimage}/`. No post-build signing step required on Linux.

### CI release pipeline

Tag pushes (`v*`) trigger `.github/workflows/release.yml`, which runs a 4-job matrix:

| Job | Runner | Target | Artifact |
| --- | ------ | ------ | -------- |
| macOS aarch64 | `macos-latest` | `aarch64-apple-darwin` | `.dmg` |
| macOS x86_64  | `macos-latest` | `x86_64-apple-darwin`  | `.dmg` |
| Linux aarch64 | `ubuntu-22.04-arm` | `aarch64-unknown-linux-gnu` | `.deb` + `.rpm` + `.AppImage` |
| Linux x86_64  | `ubuntu-22.04` | `x86_64-unknown-linux-gnu`  | `.deb` + `.rpm` + `.AppImage` |

Each release publishes 8 artifacts total.

---

## Contributing

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push (`git push origin feature/amazing`)
5. Open a Pull Request

Contributions for new pixel art sprites, Rust logic improvements, or UI enhancements are welcome.

## License

MIT. See [LICENSE](LICENSE) for details.

ani-mime

ani-mime 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

ani-mime

ani-mime 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README