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: 
    curl http://localhost:11434/api/tags
    If this times out, start Ollama: ollama serve
  3. Application logs — Check the Electron-level logs for crashes: 
    ls -lt ~/.wolffish/logs/
cat ~/.wolffish/logs/main.log
    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: 
    tail -20 ~/.wolffish/workspace/brain/corpus/$(date +%Y-%m-%d).log.md
    If you see input.received but no llm.response, the provider call is hanging or failing.
Symptoms: You’ve created a capability but Wolffish never uses it.Check these:
  1. SKILL.md triggers — Open your capability’s SKILL.md and check the triggers field in the frontmatter. Triggers must match the kinds of messages you’re sending. Example: 
    triggers:
  - "deploy"
  - "push to production"
  - "release"
  2. Debug snapshot — Send a message that should activate the capability, then check the latest debug snapshot: 
    ls -t brain/prefrontal/.debug/ | head -1
    Open it and look in the <skills> section. Is your capability listed? If not, its relevance score was below the threshold.
  3. Cerebellum loaded it — Check the event log for capability.loaded or capability.error: 
    grep "capability" brain/corpus/$(date +%Y-%m-%d).log.md
    If you see capability.error, the SKILL.md has a parsing issue (bad frontmatter, missing required fields).
  4. Lower the threshold — If the skill scores close but not above the default threshold, either add more triggers or lower ras.threshold 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: 
    danger_patterns:
  - "rm\\s+-rf"        # Good: specific
  - "rm"               # Bad: matches "format", "inform", etc.
  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: 
    grep -r "wrong information" brain/hippocampus/episodes/
  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.
  3. Rebuild the index — After editing episodes, the cortex index is stale. Delete it and Wolffish will rebuild on next restart: 
    rm brain/cortex/cortex.db
    On the next startup, cortex re-indexes all episode files from scratch.
Symptoms: Wolffish takes a long time to respond, or you see token budget warnings.Check these:
  1. Hypothalamus warnings — Look for health events: 
    grep "health" brain/corpus/$(date +%Y-%m-%d).log.md
    Warnings about token usage mean the context window is nearly full.
  2. Reduce loaded skills — If many capabilities match every message, their SKILL.md bodies consume tokens. Make triggers more specific so fewer skills load per turn.
  3. Increase RAS threshold — In config.json, raise ras.threshold (default 0.3) to be more selective about what gets included in context: 
    {
  "ras": {
    "threshold": 0.5
  }
}
  4. Check debug snapshot size — The token budget comment at the top of each debug snapshot shows usage. If <memory> or <skills> dominate, reduce those sections.
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: 
    grep "telegram\|channel" ~/.wolffish/logs/main.log
  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: 
    grep "whatsapp\|wa-web" ~/.wolffish/logs/main.log
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: 
    export default {
  init(context) { ... },
  tools: { ... }
}
  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 event log — Look for capability.error events: 
    grep "capability.error" brain/corpus/$(date +%Y-%m-%d).log.md
    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. Wolffish rebuilds it from the source markdown files on next startup:
rm ~/.wolffish/workspace/brain/cortex/cortex.db
Then restart Wolffish. The cortex re-indexes all episode files from brain/hippocampus/episodes/ — this takes a few seconds depending on how many episodes you have.
The cortex.db is a derived artifact — it’s always rebuildable from the markdown files. 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: 
    du -sh ~/.wolffish/runtime/
    Safe to delete: rm -rf ~/.wolffish/runtime/Cache/
  2. Old event logs — Should auto-clean after 7 days, but verify: 
    ls -la ~/.wolffish/workspace/brain/corpus/*.log.md
  3. Episode accumulation — Long-running instances accumulate episodes. Review and prune old ones: 
    du -sh ~/.wolffish/workspace/brain/hippocampus/episodes/
ls ~/.wolffish/workspace/brain/hippocampus/episodes/ | wc -l
  4. Debug snapshots — Should auto-clean, but check: 
    du -sh ~/.wolffish/workspace/brain/prefrontal/.debug/
If nothing else works and you want to start completely fresh:
rm -rf ~/.wolffish/
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 directories:
  • rm -rf ~/.wolffish/workspace/brain/cortex/ — 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)