Shoddy · Fettler

Quick Start

Install it, register it, and use it. Three steps, and the pages after this one give the detail.

This page sets up the tools level, which needs no setup file. When you finish, your assistant can use Fettler’s tools in one project folder. Guardrails and screenings are optional, and the last section links to them.

You need two things before you start: the archive for your platform from the latest release, and a project folder to use Fettler in.

1. Install it

Fettler is one file, and it needs no .NET runtime and no installer. In the commands below, X.Y.Z is the version you downloaded.

Windows · PowerShell

$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')
}

macOS and Linux

mkdir -p ~/.local/bin
tar -xzf fettle-X.Y.Z-osx-arm64.tar.gz -C ~/.local/bin
xattr -d com.apple.quarantine ~/.local/bin/fettle   # macOS only

Those commands also put the folder on PATH. PATH is the list of folders your terminal searches when you type a command. Now open a new terminal, because the old one still has the old PATH. Then check it:

fettle --version
fettle 2.1.0

If that says not recognised or command not found, open a new terminal and try again. If it still fails, check the folder name for a typo. Nothing later on this page works until this line does. The long version is putting it on PATH.

2. Register it with your assistant

Registering tells your assistant that Fettler exists, so the assistant can start it. Change to your project folder and run this:

fettle setup tools claude-code --local

You should see one change:

changed:
  C:\work\myproject\.mcp.json  register fettler under mcpServers
note: fettle is on PATH at C:\Users\you\AppData\Local\Programs\fettle\fettle.exe; the
      registration uses the name 'fettle'

That is the only file it writes. It does not create a .fettler.json, and it does not change the assistant’s settings. To see the change before it is made, add --dry-run, which prints the same report and writes nothing.

Note If you use another assistant, put its name in place of claude-code: claude-desktop, vscode-copilot or github-copilot. Registering each client lists the files each one uses.

Then restart your assistant. An assistant reads its list of tools when it starts, so a session that is already running will not see Fettler. In the new session, ask the assistant to call roots, or run fettle roots in the project folder yourself. Both give the same facts:

levels
  tools       on, always
  guardrails  off
  screenings  off

trees
work        C:\work\myproject  (default)
            can: list read create update rename delete

found by fettle
scratch     C:\Users\you\AppData\Local\Temp\claude\c--work-myproject\1f0c...\scratchpad
            can: list read create update rename delete
            found: this session's folder, named by the environment variable NAME
tool-results C:\Users\you\.claude\projects\c--work-myproject\1f0c...\tool-results
            can: list read
            found: in the client's folder for this project, in this session's folder; ...
memory      C:\Users\you\.claude\projects\c--work-myproject\memory
            can: list read create update rename delete
            found: in the client's folder for this project

declared by no .fettler.json, so the launch folder is the tree

Notice what each part says:

levels. The tools are on. Guardrails and screenings are off, because no file turned them on.
trees. A tree is a folder Fettler works in. With no setup file, the tree is work, the folder the assistant started in. Fettler may read and change files there, but it may not run programs.
found by fettle. These are the assistant’s own folders. Fettler found them by itself. The assistant writes drafts in scratch, reads long answers back from tool-results, and keeps notes in memory.

A folder that does not exist yet is left out. It appears on the next call, once the assistant makes it. Everything outside these trees is refused:

fettle read C:\Windows\win.ini
refused: the path is outside every declared tree. Run roots to see the trees

If the assistant has no roots tool, Fettler did not start. The usual cause is that fettle is not on PATH. Run fettle doctor in the project folder. Reading doctor’s report explains each line.

3. Use it

Now ask the assistant to search for something, or run one search yourself. Each hit comes back as the tree, the path, the line and the column, with the matched line under it. That is the form the next call takes as it is.

fettle search "TODO" --glob "**/*.cs"

You should see one line per hit, and a count at the end:

work:src/Program.cs:41:9
   41 |         // TODO: read the port from the environment
1 hit in 1 file

Then read a few lines of a file. The first line says what the file is and which lines came back, and a read that stops says how to get the rest:

fettle read src/Program.cs --to 3

work:src/Program.cs  text  utf-8  crlf  final-newline: yes  lines 1-3 of 88
    1 | using System;
    2 | 
    3 | namespace MyProject;
... 85 more line(s); pass --from 4 to continue, or --to N for a range

The tools page shows every verb, and what each one answers.

Turning on the other levels

Guardrails. To limit the assistant to folders you name and turn off its own file tools, see Guardrails.
Screenings. To stop health or customer records reaching the model, see Screenings.