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

ArtifactPathWritten By
Debug snapshotsbrain/prefrontal/.debug/context-{timestamp}.mdprefrontal.buildContext()
Event logsbrain/corpus/YYYY-MM-DD.log.mdcorpus event bus
Task filesbrain/motor/tasks/TASK-{id}.mdmotor.createTask()
Episode filesbrain/hippocampus/episodes/*.mdhippocampus.save()
All paths are relative to your workspace root (~/.wolffish/workspace/ by default).

​
Quick Diagnostic Flow

Follow this sequence when something goes wrong: 
Problem observed
    │
    ▼
┌─────────────────────────────────┐
│ 1. Check the debug snapshot     │
│    Was the right context sent?  │
└─────────────┬───────────────────┘
              │
              ▼
┌─────────────────────────────────┐
│ 2. Check the event log          │
│    Did events fire correctly?   │
└─────────────┬───────────────────┘
              │
              ▼
┌─────────────────────────────────┐
│ 3. Check the task file          │
│    Did tool execution succeed?  │
└─────────────────────────────────┘
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.

​
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:
tail -f ~/.wolffish/workspace/brain/corpus/$(date +%Y-%m-%d).log.md