> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wolffi.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to fix them

# Find Your Symptom

Common problems and their solutions. Start with the issue that matches your symptoms.

<AccordionGroup>
  <Accordion title="Wolffish doesn't respond at all">
    **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:
       ```bash theme={null}
       curl http://localhost:11434/api/tags
       ```
       If this times out, start Ollama: `ollama serve`

    3. **Application logs** — Check the Electron-level logs for crashes:
       ```bash theme={null}
       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:
       ```bash theme={null}
       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.
  </Accordion>

  <Accordion title="The agent doesn't use my capability">
    **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:
       ```yaml theme={null}
       triggers:
         - "deploy"
         - "push to production"
         - "release"
       ```

    2. **Debug snapshot** — Send a message that should activate the capability, then check the latest debug snapshot:
       ```bash theme={null}
       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`:
       ```bash theme={null}
       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`.
  </Accordion>

  <Accordion title="Tool calls always get blocked">
    **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:
       ```yaml theme={null}
       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.

    <Warning>
      Only disable safety in development. In normal use, the safety gate prevents destructive operations.
    </Warning>
  </Accordion>

  <Accordion title="Memory seems wrong or outdated">
    **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:
       ```bash theme={null}
       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:
       ```bash theme={null}
       rm brain/cortex/cortex.db
       ```
       On the next startup, cortex re-indexes all episode files from scratch.
  </Accordion>

  <Accordion title="Context is too large / responses are slow">
    **Symptoms**: Wolffish takes a long time to respond, or you see token budget warnings.

    **Check these:**

    1. **Hypothalamus warnings** — Look for health events:
       ```bash theme={null}
       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:
       ```json theme={null}
       {
         "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.
  </Accordion>

  <Accordion title="Telegram / WhatsApp not connecting">
    **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:
       ```bash theme={null}
       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:
       ```bash theme={null}
       grep "whatsapp\|wa-web" ~/.wolffish/logs/main.log
       ```
  </Accordion>

  <Accordion title="Plugin throws errors">
    **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:
       ```javascript theme={null}
       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:
       ```bash theme={null}
       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).
  </Accordion>

  <Accordion title="cortex.db is corrupted">
    **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:

    ```bash theme={null}
    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.

    <Info>
      The `cortex.db` is a derived artifact — it's always rebuildable from the markdown files. You never lose data by deleting it.
    </Info>
  </Accordion>

  <Accordion title="Wolffish uses too much disk space">
    **Symptoms**: Disk usage grows over time, especially in `~/.wolffish/`.

    **Check these locations:**

    1. **Chromium runtime cache** — The embedded browser caches aggressively:
       ```bash theme={null}
       du -sh ~/.wolffish/runtime/
       ```
       Safe to delete: `rm -rf ~/.wolffish/runtime/Cache/`

    2. **Old event logs** — Should auto-clean after 7 days, but verify:
       ```bash theme={null}
       ls -la ~/.wolffish/workspace/brain/corpus/*.log.md
       ```

    3. **Episode accumulation** — Long-running instances accumulate episodes. Review and prune old ones:
       ```bash theme={null}
       du -sh ~/.wolffish/workspace/brain/hippocampus/episodes/
       ls ~/.wolffish/workspace/brain/hippocampus/episodes/ | wc -l
       ```

    4. **Debug snapshots** — Should auto-clean, but check:
       ```bash theme={null}
       du -sh ~/.wolffish/workspace/brain/prefrontal/.debug/
       ```
  </Accordion>

  <Accordion title="How to reset everything (nuclear option)">
    If nothing else works and you want to start completely fresh:

    ```bash theme={null}
    rm -rf ~/.wolffish/
    ```

    <Warning>
      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.
    </Warning>

    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
  </Accordion>
</AccordionGroup>

## Getting Help

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

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/thewolffish/issues">
    Search existing issues or file a new one. Include the relevant event log and
    debug snapshot.
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/zWJpD3SgTt">
    Ask in the support channel. Community members and maintainers are active
    here.
  </Card>
</CardGroup>

<Tip>
  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)
</Tip>