freerebuff

Hand-made patches for the Freebuff Desktop app (macOS), distributed as patches only — never the proprietary upstream code.

Freebuff Desktop's agent harness lives in a single file inside the installed app. Its public GitHub repository contains the CLI, SDK, and agent runtime — but not the desktop app itself — so the only OSS-friendly way to share improvements is as patches against the file we all already have installed.

This repo is a play on "rebuffing": take the app, and give it a friendly nudge.

What is deliberately NOT here: any Freebuff code or binaries. The stock orchestrator.js is downloaded/extracted locally by the scripts and is gitignored. If it isn't in the repo, it can't be uploaded by mistake.

• macOS
• Freebuff Desktop installed (any recent version)
• bash, curl, unzip, patch (all present on macOS by default)
• python3 (macOS ships it; only needed for setup/mcp_setup.py)

# 1. Get the stock file — either download the latest build:
./fetch-stock.sh
#    ...or use the copy already installed on your machine:
./snapshot.sh

# 2. Apply the patches to your installed app:
./reapply.sh

# 3. Restart Freebuff and test (reapply + restart in one step):
./dev.sh

The app is not re-signed after patching; macOS stops enforcing the signature after first launch, so edited files load normally. If macOS ever refuses to launch a patched build, re-sign ad-hoc:

codesign --force --deep --sign - /Applications/Freebuff.app

Freebuff's default (codebuff) harness does not load your MCP servers out of the box. patches/0001-mcp-servers.patch fixes that: the patched harness reads MCP servers from the standard config layout and exposes their tools in every thread — alongside Freebuff's own tools, with no hardcoded server list.

~/.freebuff/mcp.json            # global — applied in every project
<project>/.freebuff/mcp.json    # per project (optional)

The format is the standard MCP mcpServers layout (same as Claude Code / Cursor), so servers you already use elsewhere carry over as-is:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "my-server"],
      "env": { "API_KEY": "..." }
    }
  }
}

Env values are written exactly as detected — a $VAR reference is kept verbatim. If a server fails to start with an unexpanded variable, replace it with a literal value.

# 1. Apply the patch to your installed app (once per Freebuff update):
./reapply.sh

# 2. Detect the MCP servers you already have in Claude Code / Codex,
#    pick which ones Freebuff should load, and write the config:
python3 setup/mcp_setup.py

The script detects servers from ~/.claude.json, ~/.codex/config.toml, and project .mcp.json files (plus manual entry), shows an interactive picker, writes the config (mode 0600 — env values may hold secrets), and offers to apply the patches.

Using the picker: ↑/↓ move · space toggles a server · a selects all · m adds one by hand · / starts a filter. While a filter is active, every printable key builds the query (so space, a, and m type instead of acting) and enter selects only the servers that match; backspace clears the filter. enter with no filter selects everything.

Non-interactive use:

python3 setup/mcp_setup.py --list                              # what's detected
python3 setup/mcp_setup.py --include my-server other-server    # enable without prompts
python3 setup/mcp_setup.py --project                           # per-project config

Restart Freebuff after changing the config — servers connect at thread start.

Trust your projects. A project's .freebuff/mcp.json runs when you open a thread in that directory. Only open threads in projects you trust — the same rule applies to .mcp.json files in Claude Code.

Note: only the codebuff (default) harness reads this config. The claude-code and codex harnesses spawn the real CLIs, which already load your MCP servers from their own configs (~/.claude.json / .mcp.json and ~/.codex/config.toml).

Updates replace the whole app bundle, wiping patches. Catch up in three steps:

./snapshot.sh        # capture the new stock file + version
# fix any rejected hunks in patches/ (.rej files) if the update moved code
./reapply.sh

See CONTRIBUTING.md — short version:

cp orchestrator.stock.js /tmp/work.js
# edit /tmp/work.js...
diff -u orchestrator.stock.js /tmp/work.js > patches/0001-short-name.patch
./reapply.sh && ./dev.sh

The repo ships an end-to-end test suite (run by the required Tests CI check):

# Setup script: detection, the interactive picker driven through a real
# pty, and config writing
pip install -r tests/requirements.txt
python3 -m pytest tests/test_setup.py -v

# Patches and MCP integration: apply the patches to stock, parse-check,
# exercise the injected freebuffMcpServers() reader, load the config through
# @codebuff/sdk, and list a real stdio MCP server's tools
npm ci --prefix tests
node --test tests/patch.test.mjs tests/mcp-integration.test.mjs

Everything that can run on Linux CI does; the final hop (the desktop app showing tools in a live thread) is manual verification — see docs/manual-verification.md.

• This project is not affiliated with Codebuff or Freebuff.
• You must install Freebuff Desktop yourself; this repo only distributes patches against the file you already have installed.
• Freebuff's own open-source components (SDK, CLI, agent runtime) are Apache-2.0; this repo's patches and tooling are Apache-2.0 too.

Apache License 2.0 — see LICENSE. Applies to the patches and tooling in this repo, not to Freebuff itself.