Tools

This page describes the tools level, which is always on and needs no file. Fettler does three kinds of work, and each kind is called a level. The tools level is the first one, and it gives you every verb, the checks that run on every call, and the folders your client keeps for this project. The client is the program your assistant runs in, such as Claude Code or VS Code. The other two levels, guardrails and screenings, stay off until a configuration file turns them on.

A folder with no file

With no .fettler.json, the folder fettle starts in becomes the one tree you work in. That folder is called the launch folder. A tree is a folder Fettler may work in, together with the list of things it may do there. The program looks for the file in the launch folder and then in each folder above it, up to the top of the drive. If it finds none, you are at the tools level.

• A file in a folder above is always found and obeyed. If a parent folder holds a .fettler.json, that file decides the trees. Ignoring it would give the assistant more than somebody wrote down.
• A broken file is a refusal, never a fallback. If the file is not valid JSON, or holds a key fettle does not know, every command refuses and names the problem. Falling back to the tools level could widen what the assistant may reach.
• A lone .fettler.local.json counts as the project file. If it sits in a folder with no .fettler.json beside it, fettle reads it as the project's file.
• --no-config skips the search for one command. fettle uses the tools level even if a file exists. --root PATH still opens one folder, read-only, for one command.

The server looks for a file again on every call until it finds one. The server is fettle running as fettle serve, the form your assistant talks to. If you write a guardrails section into a new .fettler.json while it runs, the next call obeys it with no restart. Once the server has found a file, it re-reads that same file on each call.

What went wrong, and what it looks like now

The home page lists what went wrong with the old tools. Here is the same list with the answers fettle gives instead. Each example is the terminal form. The MCP answer carries the same facts as JSON, and the JSON form of read carries a hash for every file. A path in an answer names its tree, as work:src/Glob.cs, because more than one tree is almost always open.

One search, several patterns

Two patterns go in one call. Each hit comes back as the tree, the path, the line and the column, with the matched line under it. A hit inside a PDF names its page instead. A pattern of files that matched nothing says so, rather than looking like a search that found nothing.

$ fettle search "class Glob" "IGlob" --glob "src/**/*.cs"
work:src/Fettler/Glob.cs:12:21
   12 | public sealed class Glob
work:src/Fettler/Glob.cs:31:9
   31 |     IGlob matcher = Build(pattern);
2 hits in 1 file

$ fettle search "TODO" --glob "src/**/*.ts"
0 files matched the glob; nothing was searched

One read, a cap it states

The first line gives the file's kind, encoding and line ending, and which lines of how many came back. A read that stops says how many lines are left and how to get them. A minified file, which is one enormous line, stops at the 40,000-character cap instead, and the answer says that too.

$ fettle read src/Fettler/Glob.cs --to 3
work:src/Fettler/Glob.cs  text  utf-8  lf  final-newline: yes  lines 1-3 of 212
    1 | using System;
    2 | 
    3 | namespace Fettler.Core;
... 209 more line(s); pass --from 4 to continue, or --to N for a range

An edit that refuses, because the file changed

A read returns a hash of the file. An edit takes it back as expect. If anything changed the file in between, the edit is refused before a byte is written, with exit code 6, and the fix is to read again. An anchor that matches in more than one place is refused the same way, naming the edit, so an edit never lands in the wrong place.

$ fettle edit src/Fettler/Glob.cs --expect 6f1c... --replace "IGlob" --with "IMatcher"
refused: the file changed since it was read; read it again and rebuild the edit
$ echo $LASTEXITCODE
6

A write that is refused

Two writes are refused whatever the tree grants. A write that would add a secret names the line and the kind of secret, never the value. A write to a file that says what fettle or the assistant may do names the file.

$ fettle write config/app.json --text-file app.json
refused: this write would add a credential to the file: line 14 (aws-access-key-id).
$ echo $LASTEXITCODE
12

$ fettle write .fettler.json --text-file new.json
refused: .fettler.json is a file that says what this tool and the assistant may do.
$ echo $LASTEXITCODE
11

What every call checks

These checks belong to the tools level, so they hold with no file at all. No configuration file can turn any of them off.

The governed files are .fettler.json, .fettler.local.json, .mcp.json, .picker.json, .picker.local.json, .claude/settings.json, .claude/settings.local.json, .vscode/mcp.json and the machine file fettler/fettler.json. A person changes them in an editor. Fettler never writes its own rules explains why this one refusal makes every other rule hold.

The verbs at a glance

Every verb in this table works at the tools level. Each one is a command on the command line and a tool your assistant can call. The verbs on the reference page gives each one's arguments and answers in full.

Two more verbs, run and tasks, belong to the guardrails level. At the tools level they answer that no task is declared. Declaring tasks is on the next page.

The client's folders

fettle finds three of your client's folders and opens each one as a tree, with nothing declared. Your client keeps these folders for the assistant, outside your project. The assistant writes drafts in one, reads large answers back from another, and keeps notes in the third. An assistant that may use only Fettler would have nowhere to put a draft without them.

<project> is the launch path, spelled the way the client spells it. Each folder separator and the drive colon become a hyphen, so c:\github\app becomes c--github-app. A declared tree may not use the names scratch, tool-results or memory, because fettle gives those names to these folders.

Which session is this one

Only this session's folder is opened, and fettle chooses it in a fixed order. A session is one conversation with the assistant, and the client gives each one its own folder.

1. First, a value in fettle's environment that is exactly a session folder's name. The client starts fettle with a set of environment variables. If one of them holds the name of a session folder on disk, that folder is chosen. This is an exact match, never a guess.
2. Otherwise, the newest session folder. That is right for a new conversation. It can be wrong for a conversation you resumed, which is why roots says which of the two routes it took.

• Older sessions stay outside. They sit beside this session's folder, but they are not trees. A path into one is refused in the same words as any other path outside every tree.
• The session transcripts stay outside too. The client keeps a record of each conversation beside these folders, and none of that record is a tree.
• A folder that does not exist yet is not a tree, and not a fault. It appears on the next call, once the client makes it.
• Paths in answers name their tree. When more than one tree is open, which is now almost always, each path is written as tree:path, such as scratch:draft.md.

roots says how each of these folders was found. Each one carries a found: line. For scratch it reads either this session's folder, named by the environment variable NAME or the newest session folder, because no environment variable names one. If you see the second line in a resumed conversation, check the folder before you trust it.

Companion servers

A companion is another MCP server that works in one folder you name. MCP is the protocol an assistant uses to call a tool server, and fettle is one such server. A companion's registration passes --root PATH, and that server reads and writes the files under that folder. sparky, the Shoddy calculator, is the usual case.

fettle opens a companion's folder as a tree named for the server, with read and write. The assistant can already reach that folder through the companion, so the tree grants nothing new. It lets fettle write a file there that the companion loads in the same turn.

• A declared tree with the same name and the same folder stands. Your declaration is used, with what it allows.
• The same name on a different folder is refused. Two trees cannot share one name.
• A server that passes no --root gets no tree. doctor lists it, and says that passing --root PATH would open one.

At the tools level, doctor reports each companion's folder as one line of fact. It is never a finding here, because no tree states a rule that the companion could ignore. With guardrails on, a companion folder inside a declared tree becomes a serious finding, which the guardrails page explains.

What roots says at the tools level

Ask for the roots at the start of any session. At the tools level the trees section shows only work, the launch folder. The folders fettle found for itself come after it, each with its found: line. A level that is off prints off.

$ fettle roots
levels
  tools         on, always
  guardrails    off
  screenings    off

trees
work          C:\github\app  (default)
              can: list read create update rename delete
              branch: main (local)

found by fettle
scratch       C:\Users\you\AppData\Local\Temp\claude\c--github-app\1f0c9a2e-5b7d-4c11-9e3a-7d2b8f6a4c10\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--github-app\1f0c9a2e-5b7d-4c11-9e3a-7d2b8f6a4c10\tool-results
              can: list read
              found: in the client's folder for this project, in this session's folder; this session's folder, named by the environment variable NAME
memory        C:\Users\you\.claude\projects\c--github-app\memory
              can: list read create update rename delete
              found: in the client's folder for this project
sparky        C:\Users\you\Dropbox\shoddy\halifax
              can: list read create update rename delete
              found: the --root of the sparky server registered in C:\Users\you\.claude.json

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

• The last line says where the trees came from. With no file, it says that the launch folder is the tree.
• The branch line is what this machine's copy of the repository says. It is not a statement about the remote, which only a fetch can answer.
• roots --json says the same in a form a script can read. It has a levels object, such as {"tools":{"on":true,"from":[]},"guardrails":{"on":false,"from":[]}}, and a found field on each tree fettle opened itself.

The optional tools section

A tools section changes four things about the tools level, and nothing else. You need it only when fettle's own choices are wrong for this machine or this project. Writing it does not turn on guardrails. The caps, the hashes and the readers are fixed, and no file can change them.

A path in the file is read from the folder the file sits in. A path that is a fact about one machine, such as scratch, belongs in .fettler.local.json. That is the uncommitted file beside the project file, and the personal overlay describes how it merges.

A worked tools file

This project builds into a dist folder, so its file adds that folder to the list. On the left is the whole file. On the right is what roots says with it in place. Notice that guardrails are still off, and that the tools line now names the file.

// C:\github\app\.fettler.json
{
  "tools": {
    "generated": ["bin", "obj", ".git",
                  "artifacts", "node_modules",
                  "dist"]
  }
}

$ fettle roots
levels
  tools         on, always; settings from C:\github\app\.fettler.json
  guardrails    off
  screenings    off

trees
work          C:\github\app  (default)
              can: list read create update rename delete
              branch: main (local)

found by fettle
scratch       C:\Users\you\AppData\Local\Temp\claude\...\scratchpad
              ...
memory        C:\Users\you\.claude\projects\c--github-app\memory
              ...

declared by C:\github\app\.fettler.json

The trees are the same as with no file, because a tools section declares no tree. Only a guardrails section does that, and the next page shows one.

The machine file

The machine file holds facts about one machine, and they apply to every project on it. On Windows it is %APPDATA%\fettler\fettler.json. On macOS and Linux it is ~/.config/fettler/fettler.json, or the same path under $XDG_CONFIG_HOME when that is set.

• It may hold a tools section and a screenings section. A models directory shared by every project is the usual entry.
• A guardrails section in it stops fettle loading. A tree, a task or an execute grant there would apply to every project, and no project reviewed it.
• The project's files win, section by section. fettle reads the machine file first, and then the project's files over it.
• It is not ~/.fettler.json. The search upward from a project would find that name and take your whole home folder as the tree.
• Fettler refuses to write it, like the other governed files. roots and doctor name it whenever it supplied something.

Where to go next