Skip to main content

​
Everything Is a Markdown File

Wolffish is designed to be debuggable. Every layer of the system produces human-readable markdown artifacts that you can open in any text editor. There are no binary logs, no proprietary formats, no special tools required.
If you can’t debug it by reading a markdown file, it’s a bug in Wolffish.

​
Four Sources of Truth

When something goes wrong, the answer lives in one of these four places:

Debug Snapshots

The exact context sent to the LLM on every turn. Shows what the model actually saw.

Event Logs

Chronological record of every event that fired in the system.

Task Files

Step-by-step logs of tool execution — what ran, what returned, what failed.

Episode Files

What Wolffish remembered from conversations. Stored as markdown in hippocampus.

​
File Locations

All paths are relative to your workspace root (~/.wolffish/workspace/ by default).
All four sources are indexed in cortex.db, and Wolffish can search them itself via memory_search. Often the fastest first move is simply asking Wolffish: “search your logs for what happened when I asked you to restart the server.”

​
Quick Diagnostic Flow

Follow this sequence when something goes wrong:
Most issues resolve at step 1 — the debug snapshot shows you exactly what the LLM received, so you can immediately see if something was missing or wrong.

​
Sending a Conversation to Someone Else

When the problem is someone else’s to look at, you don’t have to gather these files by hand. The diagnostic export button in any chat bundles a single conversation — its transcript, its slice of the event log, the task files it spawned, the memory and prompts behind it, and your redacted settings — into one zip, with credentials replaced by length markers and attachment media left out.

Diagnostic Export

One button, one archive: what goes in, what stays out, and where it lands.

​
Tools

You don’t need anything special to debug Wolffish. The app includes a built-in file viewer and markdown editor that lets you browse all debug artifacts without leaving Wolffish. For most debugging, it’s all you need.
For power users, VS Code is also useful because of its markdown preview and file watcher. Open the brain/ directory as a workspace and you can watch debug artifacts appear in real time.
Recommended setup:
  • VS Code with the workspace open at ~/.wolffish/workspace/brain/
  • Markdown Preview side panel for reading debug snapshots
  • File Explorer sorted by date modified to see the latest artifacts
  • Terminal with tail -f on the daily event log for live monitoring: