Installing It

This page covers the tools level, and you do most of it once per machine. First, put the fettle program on PATH. Then register it with each assistant you use. Guardrails are a choice each project makes, so this page does not set them up. The guardrails page does.

The download

Each release has one file per operating system. You download one archive, unpack one file, and need no .NET runtime.

The macOS and Linux archives are tar files, because only a tar file keeps the execute bit. The execute bit is the marker that lets a file run as a program. Each archive also holds NOTICE and LICENSE. The program has PdfPig, a library that reads PDF files, built in. PdfPig’s Apache-2.0 licence asks for its notice to travel with the program. The MIT licence asks for this project’s copyright notice in every copy.

Putting it on PATH

$dir = "$env:LOCALAPPDATA\Programs\fettle"
New-Item -ItemType Directory -Force $dir | Out-Null
Expand-Archive fettle-X.Y.Z-win-x64.zip -DestinationPath $dir -Force

Get-ChildItem $dir -Recurse | Unblock-File

$user = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($user -notlike "*$dir*") {
    [Environment]::SetEnvironmentVariable('Path', "$user;$dir", 'User')
}

fettle --version
fettle 2.1.0

mkdir -p ~/.local/bin
tar -xzf fettle-X.Y.Z-osx-arm64.tar.gz -C ~/.local/bin
fettle --version

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

xattr -d com.apple.quarantine ~/.local/bin/fettle

If you would rather not use PATH, Fettler still works. fettle setup then writes the full path of the program you ran, and says so. The PATH form is better, because a registration that names fettle keeps working after you move or update the file.

From source

You do not have to build anything else in this repository first. Fettler uses no other project here.

./scripts/fettler-build.ps1 publish X.Y.Z    # X.Y.Z names the archives
./scripts/fettler-install.ps1                # build, then install over the fettle on PATH

The archives go in artifacts/publish/. A macOS or Linux archive made on Windows has no execute bit, so a release always makes those on a macOS or Linux machine.

fettler-install.ps1 replaces the fettle that is already on PATH. It works while that copy is running. A running copy keeps serving the old build until its client restarts it, so add -Stop to end those copies once the new file is in place.

Registering each client

Registering tells an assistant client how to start Fettler. A client is the program you talk to the assistant through, such as Claude Code. One command registers Fettler with one client:

fettle setup tools claude-code --local --dry-run   # what would change
fettle setup tools claude-code --local             # change it

The first word after setup is the level. setup tools writes the registration and nothing else. It writes no .fettler.json, no deny list and no instructions. The old spelling, fettle setup claude-code, is refused, and the message shows the new one.

The clients, and the files behind them

Each client keeps its registration in its own file. Some clients have one file for the whole account and one for each project:

Claude Code in VS Code is not a fifth client. It uses exactly the same list as the Claude Code command line. Reporting it separately would print every result twice, and the two copies could disagree.

Registering it for every project

A global registration covers every project this account opens. --all does it for every client on the machine:

fettle setup tools --all --global --dry-run
fettle setup tools --all --global

This changes nothing else. Each project is at the tools level until it adds its own guardrails.

The MCP front end

fettle serve starts the MCP server. It talks over its own input and output streams. A client starts it. A person does not. If you run it by hand, it waits for input, which looks like it has stopped.

The registration setup writes is this, and nothing more:

{
  "mcpServers": {
    "fettler": { "command": "fettle", "args": ["serve"] }
  }
}

VS Code keeps the same entry under servers in place of mcpServers. setup writes the key each client reads.

The registration names no folder. The server looks for a .fettler.json in the folder the client starts it in, and in the folders above. If it finds none, that folder is the tree work. It then looks again on every call, so a file you add later takes effect on the next call. No tool lets the model point the server at a different folder.

The tools are named mcp__fettler__VERB, such as mcp__fettler__read and mcp__fettler__edit. These names differ from the client’s built-in tools, so guardrails can turn off the built-in tools and leave Fettler’s on.

The assistant is not offered setup, and a test makes sure it never is. setup writes the file that says which program the client starts. A model that could run it could point the client at a different program. A person sets up a machine, in a terminal. doctor and roots are offered, so the assistant can check its own setup.

The machine file

The machine file holds facts about this computer that every project shares. An example is where the screening models are kept. It is optional, and most machines do not need one.

The name is not ~/.fettler.json. Fettler looks for .fettler.json in each folder above the one it starts in. A file with that name in your home folder would make the whole home folder a tree.

Fettler reads the machine file first, then the project’s files. For each section, the project’s version wins. The machine file may hold two sections:

• tools holds settings for the tools, such as which folder names to skip.
• screenings holds screening settings, such as the models folder.

{
  "screenings": { "models": "C:\\screening-models" }
}

A guardrails section in the machine file is refused. Fettler will not load its settings, and every command stops with an error. A tree, a task or an execute grant there would apply to every project, and no project would have reviewed it. Fettler never writes the machine file, in the same way it never writes .fettler.json. You edit it yourself. When it supplied a setting, roots and doctor name it.

Checking it with doctor

fettle doctor checks how Fettler is installed and registered. Run it in a project folder. It prints the version and the PATH check first, then one section for each level, starting with the tools.

fettle doctor

fettle 2.1.0  C:\Users\you\AppData\Local\Programs\fettle\fettle.exe
on PATH: C:\Users\you\AppData\Local\Programs\fettle\fettle.exe

tools  on, always
  claude-code     global  absent    'fettler' is not registered in this file
                          C:\Users\you\.claude.json
  claude-code     repo    healthy   registered; runs C:\Users\you\...\fettle\fettle.exe
                          C:\work\myproject\.mcp.json
  claude-desktop  repo    n/a       this client has no project level
  scratch: C:\Users\you\AppData\Local\Temp\claude\c--work-myproject\1f0c...\scratchpad,
      found as this session's folder, named by the environment variable NAME
  tool-results: C:\Users\you\.claude\projects\c--work-myproject\1f0c...\tool-results,
      found as in the client's folder for this project, in this session's folder; ...
  memory: not found for this project. The tree appears once the client makes the folder

guardrails  off

screenings  off

The tools section shows four kinds of line:

• One row per client and reach. The reach is global for the whole account or repo for this project. Each row ends in a verdict.
• The client’s folders, with how Fettler found each one. A folder that does not exist yet is a fact, not a fault.
• The machine file, when there is one.
• Each companion server, as a fact. A companion is another MCP server whose registration passes --root PATH. Fettler opens that folder as a tree with the server’s name, so both can use the same files.

A level that is off is one line. Doctor reports findings only for a level that is on. At the tools level the one finding is 2.11: two entries in ~/.claude.json name one project folder with different spellings. Merge them by hand.

In the example, the global row is absent because only this project was registered. So doctor exits 1. If a row is broken, run setup tools again with --command naming the program, and --force to replace the old entry. Everything doctor can report lists every finding.