Wolffish - Brain-Inspired Desktop AI Agent

TL;DR

TL;DR: Wolffish is an open-source desktop AI agent that runs fully offline on your own hardware, using a 15-module brain architecture where every behavior, memory, and configuration lives in plain markdown files you can edit directly.

Source and Accuracy Notes

• Project page: wolffi.sh
• Source repository: github.com/thewolffish/wolffish-app
• License: MIT (verified via README)
• HN launch thread: news.ycombinator.com/item?id=42200000 (est.)
• Documentation: docs.wolffi.sh
• Source last checked: 2026-08-02

What Is Wolffish?

Wolffish is a desktop AI agent built with Electron that runs natively on macOS, Windows, and Linux. The tagline on the project page says it plainly: “A brain you own, not a chatbot you rent.” Every piece of state — memory, behavior, configuration — lives in readable markdown files rather than a proprietary database.

The architecture is modeled after human brain regions. Fifteen specialized runtime modules each handle one function and communicate through a typed event bus called the corpus (a reference to the corpus callosum). The modules are named after the brain parts they mirror: Thalamus routes input to LLM providers, Hippocampus handles memory storage, Amygdala gates dangerous operations, Motor executes tasks with retry logic, and so on.

Thalamus → Prefrontal → RAS → Cortex
Hippocampus → Cerebellum → Wernicke → Broca
Amygdala → Motor → Basal Ganglia → Reflection
Hypothalamus → Brainstem → Insula

The agent is local-first. It works fully offline with Ollama for local LLM inference, and cloud providers (Claude, GPT) are optional quality enhancements rather than requirements. The full stack is Node.js with React 19 on the frontend, SQLite FTS5 for the search index, and pure fetch() calls to LLM providers — no SDKs.

Setup Workflow

Step 1: Install Ollama (Required)

Wolffish requires Ollama for local LLM inference. Install it first:

# macOS / Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Or download from https://ollama.ai/download

Pull a model:

ollama pull llama3.2

Step 2: Install Wolffish

Download the latest release for your platform from wolffi.sh, or use the install script:

# macOS / Linux / Windows (via WSL)
curl -fsSL https://releases.wolffi.sh/install.sh | sh

# Windows (PowerShell)
irm https://releases.wolffi.sh/install.ps1 | iex

Or build from source:

git clone https://github.com/thewolffish/wolffish-app.git
cd wolffish-app
npm install
npm run dev

Requirements from the README:

| Tool | Minimum | | ------- | ------- | | Node.js | 24+ | | npm | 11+ |

Step 3: Configure

On first launch, Wolffish creates ~/.wolffish/workspace/ with the default brain modules. The main config lives at ~/.wolffish/workspace/config.json:

{
  "llm": {
    "local": { "enabled": true, "provider": "ollama", "model": "llama3.2" },
    "providers": [],
    "allowLocalFallback": true,
    "restrictPowerfulModels": true
  },
  "safety": { "bypassPermissions": false, "blockCredentials": true },
  "locale": "en",
  "theme": "system"
}

Step 4: Edit the Brain (Optional)

The most distinctive Wolffish feature is that behavior lives in markdown files you can edit directly:

| File | Purpose | |------|---------| | brain/identity/soul.md | Agent personality, tone, behavioral guidelines | | brain/identity/user.md | Who you are — name, role, tech stack, preferences | | brain/prefrontal/agents.md | Operational manual, tool rules, procedures | | brain/brainstem/heartbeat.md | Scheduled background jobs (cron-managed) |

Change how the agent behaves by editing a markdown file. No code changes needed.

Brain Module Reference

| Module | Function | Brain Analogy | |--------|----------|---------------| | Thalamus | Routes input to LLM providers | Sensory gateway | | Prefrontal | Assembles context for the LLM | Executive function | | RAS | Filters relevant content by attention | Reticular Activating System | | Cortex | Fast retrieval index (SQLite FTS5) | Pattern matching | | Hippocampus | Memory storage and consolidation | Memory center | | Cerebellum | Discovers and loads capabilities | Motor coordination | | Wernicke | Parses LLM output, extracts tool calls | Language comprehension | | Broca | Streams responses to the UI | Language production | | Amygdala | Safety gate for dangerous operations | Threat detection | | Motor | Executes tasks with retry logic | Motor cortex | | Basal Ganglia | Records raw tool outcomes (telemetry) | Reward processing | | Reflection | Nightly self-review, distilled playbooks | Sleep consolidation |

Capabilities

Wolffish ships with 20+ built-in capabilities:

• Shell command execution
• Filesystem operations
• Git operations
• Browser automation
• Document processing (PDF, DOCX, XLSX, images)
• Speech synthesis
• And more via the Cerebellum capability loader

Multi-channel support lets you talk to the same agent via the desktop app, Telegram, or WhatsApp.

Safety Model

The Amygdala module gates every tool call using patterns defined in each capability’s SKILL.md:

| Classification | Behavior | |----------------|---------| | Danger patterns | Blocked completely — regex-matched destructive operations | | Confirm patterns | Requires explicit user approval before execution | | Safe | Executes immediately |

The default config sets blockCredentials: true and bypassPermissions: false for cautious out-of-the-box behavior.

Practical Evaluation Checklist

• Local-first: runs fully offline with Ollama
• Markdown-driven: all state is human-readable and editable
• Brain-inspired: 15 modules with defined responsibilities
• Multi-channel: desktop app, Telegram, WhatsApp
• Safety-gated: dangerous operations require explicit approval
• Provider cascade: Claude → GPT → Ollama fallback
• Bilingual: English and Arabic with full RTL support
• Open source: MIT licensed, source on GitHub

FAQ

Q: Does Wolffish require an internet connection? A: No. It runs fully offline using Ollama for local LLM inference. Cloud providers (Claude, GPT) are optional and disabled by default.

Q: How is this different from Claude Desktop or ChatGPT? A: Everything runs on your own hardware. No data leaves your machine. The behavior is also fully customizable — edit markdown files to change how the agent thinks and acts, without touching code.

Q: What models does it support? A: Any Ollama model locally, plus Claude and GPT via API keys. The provider cascade falls back through the list: Claude → GPT → Ollama.

Q: Can I run it on a server? A: The primary interface is the desktop app, but the Telegram and WhatsApp channels enable remote interaction. The agent itself runs wherever you launch it.

Conclusion

Wolffish stands out for its local-first philosophy and its unusual architecture: 15 brain-module components that each do one thing, communicating through an event bus, with all state in plain markdown. That makes it unusually transparent — you can read exactly what the agent knows about you (brain/identity/user.md), what rules it follows (brain/prefrontal/agents.md), and what it remembers (~/.wolffish/workspace/brain/hippocampus/).

The markdown-is-truth design is the real differentiator. Most AI agents are black boxes you prompt around. Wolffish gives you a filesystem of readable files you can edit directly, and the agent reads them on every run. If you want a privacy-preserving desktop agent that’s genuinely customizable without plugins or paid plans, Wolffish is worth a look.

Install it at wolffi.sh, read the docs at docs.wolffi.sh, or dig into the source at github.com/thewolffish/wolffish-app.