The complete guide to owning your brain.
Official documentation for Wolffish — the local-first, markdown-powered personal AI desktop agent. Published at docs.wolffi.sh.
Fully bilingual (English + Arabic). Covers everything from first launch to writing custom brain modules.
Demo walkthrough |
Cinematic launch |
Cinematic reveal |
| Page | What You'll Learn |
|---|---|
| Overview | What wolffish is and how it works at a glance |
| Philosophy | The 8 design principles that guide every decision |
| Installation | Download, prerequisites, build from source |
| First Launch | What happens when you run wolffish for the first time |
| Quickstart | 5 steps to send your first message and inspect the internals |
| Page | What You'll Learn |
|---|---|
| Overview | Real-world workflows that show what Wolffish can do end to end |
| Setting Up for Success | Permissions, prerequisites, and tips for reliable autonomous runs |
| AI News Daily LinkedIn Post | Automated daily AI news curation and LinkedIn posting — zero API, zero third-party code |
| Page | What You'll Learn |
|---|---|
| God's Creation | How 14 human brain regions map to software modules |
| Architecture Overview | 15-module runtime, event bus, deterministic pipeline |
| Pipeline | Step-by-step message flow with token budget allocation |
| Brain Modules | Complete reference for all 15 modules |
| Workspace | The ~/.wolffish/ directory structure |
| Event Bus | 30+ typed events, logging, cleanup |
| Page | What You'll Learn |
|---|---|
| Overview | Pure skills vs plugins, discovery, relevance scoring |
| SKILL.md Reference | Complete frontmatter format, tool schemas, safety patterns |
| Writing Plugins | Build capabilities with executable code |
| Built-in Capabilities | The 20+ capabilities that ship with wolffish |
| Page | What You'll Learn |
|---|---|
| Overview | Multi-channel architecture, TurnRunner, TurnRouter |
| Telegram | Bot setup, inline buttons, HTML formatting |
| Baileys integration, QR login, voice transcription |
| Page | What You'll Learn |
|---|---|
| Overview | Stateless architecture, credential handling |
| Browser Extension | Control Chrome/Brave with 44 tools via WebSocket |
| Google Workspace | Gmail, Drive, Calendar, Sheets (OAuth) |
| GitHub | Repos, issues, PRs, workflows (PAT) |
| Notion | Pages, databases, search (API token) |
| Page | What You'll Learn |
|---|---|
| Overview | Three-tier memory system and context budget |
| Episodes | Daily logs — instant, no-LLM append |
| Consolidation | Nightly compaction into weekly summaries |
| Knowledge | Long-term facts and manual curation |
| Feedback Loop | How wolffish learns from approvals and rejections |
| Page | What You'll Learn |
|---|---|
| soul.md | Agent personality — tone, verbosity, guidelines |
| user.md | Your profile — name, role, stack, preferences |
| agents.md | Operational procedures and tool rules |
| config.json | App settings and provider configuration |
| Providers | DeepSeek, Claude, OpenAI, Ollama setup and cascade |
| Variables | Secrets and environment-style values |
| Heartbeat | Cron-like scheduling for autonomous jobs |
| Page | What You'll Learn |
|---|---|
| Overview | "If you can't debug it by reading markdown, it's a bug" |
| Debug Snapshots | Exact context sent to the LLM |
| Event Logs | Chronological system events |
| Task Files | Tool execution with args, output, duration |
| Troubleshooting | Common issues and fixes |
| Page | What You'll Learn |
|---|---|
| Creating Capabilities | Step-by-step guide to building a new skill |
| Advanced Plugins | Complex logic, API calls, stateful plugins |
| Adding Channels | Build a new communication channel |
| Community Capabilities | Share and discover community skills |
| Safety Patterns | Amygdala classification, confirm vs block |
| Page | What You'll Learn |
|---|---|
| Setup | Dev environment, commands, path aliases |
| Project Structure | Codebase layout and conventions |
| Contributing | How to contribute to wolffish |
| Adding Brain Modules | Create new runtime modules |
Every piece of agent state — personality, memory, capabilities, configuration, debug output — lives in readable, editable markdown files. The TypeScript code is pure plumbing: it reads markdown, calls LLMs, executes tools, and writes markdown back. To change what the agent does, you edit markdown.
Wolffish maps human brain regions to 15 specialized software modules. Each handles exactly one function and communicates through a typed event bus (the corpus). The pipeline is deterministic — the LLM adds creativity at exactly one point. Everything else is predictable code.
| Tier | Speed | Source | Lifespan |
|---|---|---|---|
| Episodes | Instant (no LLM) | Appended every turn | Days |
| Consolidated | Nightly (LLM-powered) | Compressed from episodes | Weeks |
| Knowledge | Manual or promoted | Curated facts | Permanent |
The amygdala module gates every tool call against patterns defined in SKILL.md frontmatter. No hard-coded guardrails — the safety system is as transparent and editable as everything else. Destructive operations require explicit approval; outcomes feed back into the learning system.
Can work 100% offline with Ollama, or cloud-only with no local models — your choice. All providers (DeepSeek, Xiaomi MiMo, Kimi, MiniMax, Anthropic, OpenAI, Ollama) are optional; configure any combination. Provider cascade: DeepSeek → MiMo → Kimi → MiniMax → Claude → OpenAI → Ollama (skipping unconfigured providers). We recommend starting with DeepSeek or MiMo — they handle complex agentic tasks well at a fraction of the cost. Upgrade to Anthropic or OpenAI only if execution isn't reliable enough for a specific workflow.
wolffish-docs/
├── introduction/ What wolffish is and why
├── getting-started/ Install, first launch, quickstart
├── use-cases/ Real-world workflows — AI news posting, and more
├── architecture/ Brain modules, pipeline, event bus, workspace
├── capabilities/ Skills, plugins, built-in capabilities
├── channels/ Electron, Telegram, WhatsApp
├── integrations/ Google, GitHub, Notion, Brave
├── memory/ Episodes, consolidation, knowledge, feedback
├── configuration/ soul.md, user.md, agents.md, config.json, heartbeat
├── debugging/ Snapshots, event logs, task files
├── extending/ Create capabilities, plugins, channels, safety
├── development/ Setup, structure, contributing
├── ar/ Full Arabic translation (parallel structure)
├── static/ Icons, favicon, CSS
└── docs.json Navigation structure and site config
- Fumadocs — Next.js documentation framework
- MDX — Markdown with JSX components (CardGroup, Accordion, Tabs)
- Bilingual — Full English + Arabic with RTL support
Documentation improvements are always welcome. Each .mdx file is self-contained — edit it directly and submit a PR.
To add a new page:
- Create the
.mdxfile in the appropriate section folder - Add an entry to
docs.jsonunder the correct tab and section - If bilingual, create the parallel page in
ar/
- Live docs — docs.wolffi.sh
- App repo — wolffish-app
- Website — wolffi.sh
- Discord — Join
- X — @younesbites
- Reddit — u/younesbites
MIT License — Copyright (c) 2026 Younes Alturkey