Skip to main content

​
Find Your Symptom

Common problems and their solutions. Start with the issue that matches your symptoms.
Symptoms: You type a message and nothing happens. No response, no error.Check these in order:
  1. Provider status — Open Settings and verify your LLM provider is configured and reachable. If using a cloud provider (OpenAI, Anthropic), check their status page.
  2. Ollama running — If using a local model, confirm Ollama is running:
    If this times out, start Ollama: ollama serve
  3. Application logs — Check the Electron-level logs for crashes:
    Look for unhandled exceptions or connection errors.
  4. Event log — If the app appears responsive but the LLM isn’t replying, check if events are firing:
    If you see message.received but no llm.response, the provider call is hanging or failing.
Symptoms: You’ve created a capability but Wolffish never uses it.How discovery works now: a core set of capabilities is always loaded; everything else appears as one line in the prompt’s <capabilities> index and loads on demand when the model calls tool_search (which matches capability names, descriptions, triggers, and tool names) or calls one of its tools directly.Check these:
  1. It’s in the index — Send any message, then open the latest debug snapshot:
    Look in the <capabilities> section. If your capability isn’t listed at all, its SKILL.md failed to parse — check the frontmatter (bad YAML, missing required fields).
  2. Make it findable — tool_search is a term search. Give the SKILL.md a descriptive name and description, and add triggers covering the words you’d naturally use:
  3. Ask for it explicitly — Tell Wolffish “use tool_search to find a deployment capability”. If that loads and runs it, the plugin is fine and only the descriptions need sharpening.
  4. Pin it — If the capability should always be loaded (schemas shipped on every request), add it to pinnedCapabilities in config.json:
Symptoms: Every tool call triggers a safety confirmation or gets denied.Check these:
  1. danger_patterns in SKILL.md — The amygdala checks tool arguments against danger_patterns regexes defined in the capability’s SKILL.md. If your patterns are too broad, they’ll match everything:
  2. confirm_patterns — These require user confirmation but don’t block. If you want the tool to run without asking, remove the matching pattern from confirm_patterns.
  3. Bypass setting — For development, you can disable safety confirmations in Settings. This skips the amygdala gate entirely.
Only disable safety in development. In normal use, the safety gate prevents destructive operations.
Symptoms: Wolffish references information that’s wrong, outdated, or from the wrong context.Fix it directly:
  1. Read the episode file — Episodes are plain markdown. Find the offending memory:
  2. Edit or delete it — Open the episode file and fix the content, or delete the file entirely. Episodes are just markdown — edit them like any other file. The same goes for the knowledge files under brain/hippocampus/knowledge/ — durable facts often live there.
  3. The index follows you — No manual rebuild needed: the file watcher re-indexes edited files while Wolffish runs, and every launch does an incremental diff. If the index still looks wrong, force a full rebuild:
    On the next startup, cortex re-indexes the whole workspace (about a second, even for gigabytes).
Symptoms: Wolffish takes a long time to respond, or you see token budget warnings.A fresh conversation’s system prompt is ~5k tokens by design, and long conversations automatically fold into a rolling summary plus the recent verbatim tail — so a bloated context is the exception, not the norm. When it happens:
  1. Hypothalamus warnings — Look for health events:
    Warnings about token usage mean the context window is nearly full.
  2. Check the debug snapshot header — estimated tokens at the top of the latest snapshot shows the prompt’s size. If it’s far above ~5k, an oversized always-included file is the usual culprit: a huge soul.md, user.md, or agents.md lands in every prompt.
  3. Watch the context meter — In the context meter beside the chat input, the numerator is the provider-billed tokens of the last request and the denominator is the model’s full context window. Big single tool results (a giant file read, a huge page fetch) inflate a turn temporarily; stale large tool results are replaced with recovery-pointer stubs on later turns.
  4. Pinned capabilities — Every capability in pinnedCapabilities ships its full tool schemas on every request. Pin sparingly; tool_search loads the rest on demand (capped at 10 active non-core capabilities per conversation).
Symptoms: Channel shows as disconnected, messages aren’t received.For Telegram:
  1. Verify your bot token in Settings is correct
  2. Check internet connectivity
  3. Look for connection errors:
  4. Telegram bots require polling — if Wolffish was offline, it reconnects automatically on restart
For WhatsApp:
  1. The QR code in Settings must be scanned with your phone
  2. The session expires if your phone is offline for 14+ days — re-scan the QR
  3. Check for session errors in the logs:
Symptoms: A capability’s plugin fails to load or tools error at runtime.Check these:
  1. Export structure — plugin/index.mjs must export a default object:
  2. Tool names match — Tool names in the plugin must exactly match the names declared in SKILL.md frontmatter tools: section.
  3. Args match schema — The JSON schema in SKILL.md must match what the plugin function expects. Type mismatches cause silent failures.
  4. Check the application log — Capability load failures land in the app log:
    The error message usually points to the exact issue (missing export, syntax error, bad import).
Symptoms: Search doesn’t work, memory retrieval fails, errors mentioning SQLite or FTS5.Fix: Delete the database (and its -shm/-wal companions). Wolffish rebuilds it from the source files on next startup:
Then restart Wolffish. The cortex re-indexes everything — episodes, knowledge, conversations, tasks, logs, usage, artifacts — in about a second, even for a multi-gigabyte workspace. A normal launch (no deletion) only runs an incremental diff, which takes milliseconds.
The cortex.db is a derived artifact — it’s always rebuildable from the files on disk. You never lose data by deleting it.
Symptoms: Disk usage grows over time, especially in ~/.wolffish/.Check these locations:
  1. Chromium runtime cache — The embedded browser caches aggressively:
    Safe to delete: rm -rf ~/.wolffish/runtime/Cache/
  2. Old event logs — Should auto-clean after 7 days, but verify:
  3. Episode accumulation — Long-running instances accumulate episodes. Review and prune old ones:
  4. Debug snapshots — Capped at the 50 most recent (older ones are rotated out automatically), but verify:
If nothing else works and you want to start completely fresh:
This deletes all configuration, memories, episodes, capabilities, and logs. Wolffish will run first-launch setup again. Only do this if you’re prepared to lose everything.
For a less destructive reset, delete only specific pieces:
  • rm ~/.wolffish/workspace/brain/cortex.db* — rebuild search index only
  • rm -rf ~/.wolffish/workspace/brain/hippocampus/episodes/ — clear all memories
  • rm -rf ~/.wolffish/workspace/brain/corpus/ — clear event logs
  • rm -rf ~/.wolffish/workspace/brain/prefrontal/.debug/ — clear debug snapshots

​
Getting Help

If you’ve tried the steps above and the problem persists:

GitHub Issues

Search existing issues or file a new one. Include the relevant event log and debug snapshot.

Discord Community

Ask in the support channel. Community members and maintainers are active here.
When filing a bug report, include: 1. The debug snapshot from the failing turn 2. The relevant section of the event log 3. The task file (if a tool was involved) 4. Your config.json (redact API keys)