ShibaCat documentation

Requirements

• OS: Windows 10 or 11, 64-bit
• Node.js 18 or newer (for building from source)
• Package manager: npm or pnpm
• Optional: a microphone for voice input, and API keys for AI providers (see Voice & providers)

No API keys are required to run the cat — avatar, animation, eye tracking and workspace awareness work fully offline.

Run from source

ShibaCat is a standard Node/Electron project. After getting the source tree (shibacat-assistant):

> npm install

# development (Vite + Electron with hot reload)
> npm run dev

# production build (typecheck + renderer + main/preload bundles)
> npm run build

# unit tests
> npm test

# build a Windows NSIS installer into ./release
> npm run dist

The installer target is x64 NSIS via electron-builder. For quick local testing without an installer, npm run dev is enough.

Avatar controls

Settings

The settings window has four sections plus provider and MCP panels:

• Avatar & animation — scale, eye tracking (look-at), blinking, breathing, tail & ear dynamics
• Window — always-on-top, click-through mode, start with Windows
• Brain & voice — API keys for LLM, speech-to-text and text-to-speech providers
• Cat mood — manual mood override
• Provider gateway — pick providers/models per capability and test real connections
• MCP servers — add stdio MCP servers (see below)

The tray menu also toggles always-on-top and click-through directly. Click-through makes the cat ignore the mouse so it never blocks clicks in apps behind it — cursor tracking keeps working.

Voice & providers

Voice works in two modes depending on what you configure:

• Streaming (recommended): set a Deepgram key for near-instant streaming transcription (nova-2, Bahasa Indonesia).
• Fallback: a Groq key enables per-utterance Whisper transcription with a second or two of extra latency.

Spoken replies need a text-to-speech key (OpenAI-compatibletts-1); without one the cat still moves its mouth along a local text-driven lip-sync timeline. Reasoning/chat runs through any OpenAI-compatible endpoint — OpenAI, Groq, OpenRouter, DeepSeek or a custom base URL — plus Anthropic and Gemini adapters.

Agent mode

Agent mode turns the cat into a task runner with real tools. It isexperimental: the pipeline is implemented and unit-tested, but it is currently driven through the developer/debug interface rather than a finished settings toggle.

What it can use

• Filesystem — read/write/edit/copy/move/delete, locked to a workspace folder you choose
• Terminal — command execution with automatic risk classification
• Browser — an isolated hidden Chromium window for page automation
• Web — fetch pages and run searches
• Memory — long-term facts about you and your projects
• Skills & sub-agents — procedural playbooks and delegated tool runs
• MCP tools — anything your configured MCP servers expose

How it stays safe

• File paths are resolved and checked against the workspace scope; traversal, UNC paths, protected system areas and symlink escapes are rejected
• Secrets (API keys, passwords, private keys) found in tool output are redacted automatically
• Terminal commands are classified SAFE/LOW/MEDIUM/HIGH/CRITICAL; anything above the auto-run threshold requires your approval on the cat itself — allow once, allow for the session, or deny
• CRITICAL-classified operations always ask, and can never be remembered
• Sessions are capped at 24 steps / 15 minutes, identical repeated tool calls are stopped, and every execution lands in an audit trail

Skills

Skills are markdown playbooks the agent can load for a task. ShibaCat ships with built-in skills (testing, debugging methodology, frontend design, Git practices and more), and loads your own from your user data folder:

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

Skills can be enabled or disabled per name in the settings vault, and the registry resolves depends_on chains (and detects cycles) before a skill is used.

MCP servers

Add Model Context Protocol servers in Settings → MCP Servers by giving each one a name plus a launch command and args (stdio transport). Their tools are registered into the agent's tool registry at session start and are subject to the same approval flow as built-in tools. HTTP-based MCP servers are supported by the runtime as well.

Keyboard shortcuts

Troubleshooting

• The cat shows an error box instead of the model. The VRM asset could not be loaded — make sure assets/models/shiba_cat.vrmis present relative to the app.
• Workspace detection is stuck on UNKNOWN. The local PowerShell sensor may be blocked by security software. ShibaCat backs off gracefully and the cat keeps living with a generic profile.
• Voice does nothing. Voice needs a provider key (seeVoice & providers) and microphone access. Without them, voice stays off — this is intentional.
• Rendering froze after a driver event. On WebGL context loss the cat pauses rendering and resumes automatically when the context is restored.
• Where are the logs? The main process writes a rolling log to %APPDATA%\shibacat-assistant\logs\shibacat.log(rotated at 512 KB).