Three Ways to Contribute

There are three ways to contribute to Wolffish:

Code

TypeScript — fix bugs, add features, improve the runtime.

Capabilities

SKILL.md + optional plugin — teach Wolffish new things.

Documentation

MDX pages — improve or translate the docs.

Code Contributions

Workflow

Fork the repo and clone your fork

Create a feature branch:

git checkout -b feature/my-thing
# or
git checkout -b fix/the-bug

Make your changes
Verify:
npm run typecheck && npm run lint
Test frontend changes in the browser (npm run dev)
Commit with conventional format
Push and open a PR against main

Commit Messages

Use Conventional Commits:

type(scope): subject

feat(runtime): add token counting to prefrontal
fix(renderer): prevent flash on theme switch
refactor(motor): simplify retry logic
docs(capabilities): add plugin lifecycle diagram

Common types: feat, fix, refactor, docs, chore, test

Code Conventions

No comments unless the WHY is non-obvious

Code should be self-documenting. If you need a comment, explain WHY, not WHAT.

// Bad
// Get the user
const user = getUser()

// Good — the WHY is non-obvious
// Fallback to default user when workspace has no user.md yet
const user = getUser() ?? DEFAULT_USER

No over-abstraction

Don’t create abstractions until you have three concrete uses. A bug fix is a bug fix — don’t refactor the world around it.

No unnecessary dependencies

Before adding a package, check if the standard library or existing deps already cover it. Wolffish uses fetch() directly instead of Axios, mitt instead of EventEmitter3, etc.

IPC is the ONLY main-renderer channel

Never import from @main/* in renderer code. All communication goes through IPC channels defined in the preload layer.

// In renderer — use the exposed API
const result = await window.api.someChannel(args)

// NEVER do this in renderer
import { something } from '@main/some-module' // Breaks process isolation

Never write outside ~/.wolffish/

The app’s entire footprint lives in ~/.wolffish/. Never write to Desktop, Documents, temp directories, or anywhere else. If a feature needs storage, put it inside the workspace.

Capability Contributions

Capabilities are the easiest way to extend Wolffish without touching core code.

Creating a Capability

Create a folder in src/defaults/workspace/brain/cerebellum/:

brain/cerebellum/my-capability/
├── SKILL.md          # Required — defines triggers, tools, behavior
└── plugin/           # Optional — custom tool logic
    └── index.mjs

Write SKILL.md with proper frontmatter:

---
name: my-capability
description: What this capability does
triggers:
  - keyword that activates this
  - another trigger phrase
tools:
  - name: my_tool
    description: What this tool does
    parameters:
      type: object
      properties:
        input:
          type: string
          description: The input to process
      required: [input]
danger:
  - pattern: "rm -rf"
    reason: "Destructive file operation"
---

# Instructions for the LLM

When the user asks about [topic], use the `my_tool` tool to...

Test with cloud models (DeepSeek, Claude, GPT) and local models (Ollama) — behavior should be consistent.

Capabilities can also live in standalone repos. Users clone them directly into their ~/.wolffish/workspace/brain/cerebellum/ folder:

cd ~/.wolffish/workspace/brain/cerebellum/
git clone https://github.com/you/wolffish-capability-name.git

Wolffish discovers them on next launch.

Documentation Contributions

Setup

Docs live in the wolffish-docs repo (separate from the app):

git clone https://github.com/thewolffish/wolffish-docs.git
cd wolffish-docs
npx mintlify dev

Format

MDX files with Mintlify components (Card, CardGroup, Note, Tip, Warning, Tabs, Accordion, etc.)
Keep content practical and concise
Use code blocks extensively

Translations

Arabic translations are required for all new pages. The ar/ directory mirrors the English structure exactly.

For every new page at section/page.mdx, create a corresponding ar/section/page.mdx with the same structure and translated content. Update mint.json navigation for both versions.

Development Setup

Get the dev environment running first.

Adding Brain Modules

Contributing a new runtime module? Read this.

Get Started

Core Concepts

Capabilities

Channels

Models

Integrations

Memory & Learning

Configuration

Debugging

Extending Wolffish

Development

Contributing

Three Ways to Contribute

Code

Capabilities

Documentation

Code Contributions

Workflow

Commit Messages

Code Conventions

Capability Contributions

Creating a Capability

Documentation Contributions

Setup

Format

Translations

Development Setup

Adding Brain Modules

​Three Ways to Contribute

Code

Capabilities

Documentation

​Code Contributions

​Workflow

​Commit Messages

​Code Conventions

​Capability Contributions

​Creating a Capability

​Sharing Capabilities

​Documentation Contributions

​Setup

​Format

​Translations

Development Setup

Adding Brain Modules

Three Ways to Contribute

Code Contributions

Workflow

Commit Messages

Code Conventions

Capability Contributions

Creating a Capability

Sharing Capabilities

Documentation Contributions

Setup

Format

Translations