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

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
```bash

The agent is local-first. It works fully offline with [Ollama](https://ollama.ai) 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:

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

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

Pull a model:

```bash
ollama pull llama3.2
```bash

### Step 2: Install Wolffish

Download the latest release for your platform from [wolffi.sh](https://wolffi.sh), or use the install script:

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

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

Or build from source:

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

**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`:

```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.