Skip to main content

​
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

  1. Fork the repo and clone your fork
  2. Create a feature branch: 
    git checkout -b feature/my-thing
# or
git checkout -b fix/the-bug
  3. Make your changes
  4. Verify: 
    npm run typecheck && npm run lint
  5. Test frontend changes in the browser (npm run dev)
  6. Commit with conventional format
  7. 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

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
Don’t create abstractions until you have three concrete uses. A bug fix is a bug fix — don’t refactor the world around it.
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.
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
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

  1. 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
  2. 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...
  3. Test with cloud models (DeepSeek, Claude, GPT) and local models (Ollama) — behavior should be consistent.

​
Sharing Capabilities

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.