ShibaCat documentation

Requirements & Platform Support

ShibaCat runs across major desktop platforms:

• Node.js: v18.0.0 or newer (optional for binary CLI installers)
• Audio: Microphone for voice conversations (optional)
• Keys: AI provider API keys (optional — core avatar works fully offline)

Installation & Setup

Install ShibaCat directly using your system's terminal:

Windows (PowerShell)

> irm https://shibacat.dreenkadev.site/install.ps1 | iex

macOS & Linux (Terminal)

$ curl -fsSL https://shibacat.dreenkadev.site/install.sh | bash

Node.js / NPX CLI

$ npx shibacat@latest init

Developer Build (From Source)

> git clone https://github.com/dreenkaDev/shibacat-assistant.git
> cd shibacat-assistant
> npm install
> npm run dev

Avatar controls

Settings & 10 Languages (i18n)

The settings window provides reactive control with zero page reload required when switching options:

• Language (10 Locales): English, Indonesian (Bahasa Indonesia), Japanese (日本語), Korean (한국어), Simplified Chinese (简体中文), Spanish (Español), Portuguese (Português), French (Français), German (Deutsch), and Arabic (العربية). UI text, chat form placeholders, and reasoning fallback responses update instantly.
• Avatar & Motion: Size slider, screen-space eye tracking toggle, procedural blinking, breathing, spring-bone ear/tail dynamics, and autonomous idle behaviors (grooming, stretching, napping).
• Chat & Bubble: Bubble scale, head gap distance, and paw toggle opacity.
• Mood: Homeostatic autonomous mood engine or manual override (Neutral, Happy, Playful, Excited, Curious, Surprised, Relaxed, Sleepy, Annoyed, Angry, Sad) with ambient particle effects.
• Window: Always-on-top, click-through transparency mode (cat ignores clicks to avoid blocking background apps), and launch on system login.

Provider Gateway (Reasoning, STT & TTS)

ShibaCat includes a unified Provider Gateway that supports primary and fallback chaining for all AI capabilities:

• Reasoning (LLM): OpenAI (GPT-4o, o3-mini), Anthropic (Claude 3.5 Sonnet), Google Gemini (Gemini 2.5 Flash / Pro), DeepSeek, Groq, or any custom OpenAI-compatible endpoint.
• Speech-to-Text (STT): Real-time streaming transcription via Deepgram (nova-2) or utterance-based Whisper via Groq with automatic fallback.
• Text-to-Speech (TTS): Natural feline voice synthesis with Fish Audio, ElevenLabs, OpenAI TTS (tts-1), or Speechma. Without TTS keys, local procedural lip-sync takes over automatically.

Companion, Wellness & Memory

• Persona Profiles: Select between Default (Friendly), Playful (Cheeky), Lazy (Terse), and Serious (Concise) personas to shape speech style and idle animations.
• Break Buddy: Built-in 25/5 Pomodoro wellness notifications and stretching reminders after prolonged focus sessions.
• Do Not Disturb & Quiet Hours: Automatic suppression of remarks during fullscreen games, meetings, or custom blocked applications, plus scheduled quiet hours.
• Private Long-Term Memory: Opt-in storage of learned user facts with complete memory inspection, single-item deletion, mass clear, export, and import.

Agent mode

Agent mode enables ShibaCat to execute automated workflows on your machine upon request. It is experimental and strictly approval-gated.

Available Tools

• Filesystem: Safe read, write, edit, copy, move, and directory inspection locked strictly inside your designated workspace folder.
• Terminal: Shell execution with automatic risk classification (SAFE, LOW, MEDIUM, HIGH, CRITICAL).
• Browser: Isolated hidden Chromium automation for web reading and interaction.
• Memory: Long-term user and project knowledge recall.
• Skills & MCP: Extensible skills library and custom external tools via Model Context Protocol.

Safety Guardrails

• Path traversal, UNC paths, and symlink escapes outside the workspace root are blocked before execution.
• API keys, passwords, and private tokens detected in output files are redacted automatically.
• Operations above low risk require explicit approval cards on the avatar UI.
• Sessions are bounded by step and timeout limits with a full immutable audit log.

Skills

Skills are markdown playbooks the agent loads on demand. ShibaCat includes built-in methodologies (testing, debugging, frontend architecture, Git practices) and supports custom user skills loaded from:

%APPDATA%\shibacat-assistant\skills\<my-skill>\SKILL.md

MCP servers

Add Model Context Protocol (MCP) servers in Settings → Agent Tools (MCP) with custom launch commands and arguments (stdio or HTTP transport). Their capabilities are automatically registered in the tool catalog at the start of agent sessions.

Keyboard shortcuts

Troubleshooting

• Avatar shows a placeholder or error box: Ensure the VRM asset assets/models/shiba_cat.vrm exists in the project assets directory.
• Workspace detection shows UNKNOWN: If background PowerShell sensor polling is restricted by system security policies, ShibaCat degrades gracefully to ambient idle behavior.
• Voice does not respond: Check that a valid STT/Reasoning/TTS key is configured in Settings → Providers and that microphone permissions are granted.
• Where are logs stored? The runtime writes rotating logs to %APPDATA%\shibacat-assistant\logs\shibacat.log (or ~/.config/shibacat-assistant/logs/ on Linux).