# 4D Forest (fm) for AI agents

4D Forest is a file manager for Windows with an index of the whole disk, kept current by its service. Its program, `fm.exe`, is also a local MCP server (stdio): `fm.exe mcp`. Through it you search every file of the disk in milliseconds, get a folder's size and file count without walking it, read a file's history (created, changed, moved, replaced), look at pictures as numbered thumbnail sheets, and propose changes to the disk as a plan the person runs or declines in fm's window. The index stays on the person's computer; you read only what you ask for.

## Connect fm to your own program

1. **Find fm.** The installed program is `%LOCALAPPDATA%\Programs\3d_fm\fm.exe` (PowerShell: `"$env:LOCALAPPDATA\Programs\3d_fm\fm.exe"`).
2. **Not there?** fm is not installed. Do not download or install it yourself: tell the person what fm would give them and ask them to install it from https://4dforest.com/ (the installer puts fm in their user folder; no administrator needed).
3. **Write fm into your program's settings.** fm does it itself:

   ```text
   "%LOCALAPPDATA%\Programs\3d_fm\fm.exe" agents add <program>
   ```

   where `<program>` is yours: `claude-code`, `claude-desktop`, `cursor`, `vscode`, `vscode-insiders`, `windsurf`, `codex`, `gemini-cli`, `antigravity`, `lm-studio`, `kiro`. `fm.exe agents` lists the programs found and whether fm is connected to each. It keeps everything else in the settings file as it was; a settings file with comments it does not touch (it says so).

   Or with your program's own command:

   ```text
   claude mcp add --scope user fm -- "%LOCALAPPDATA%\Programs\3d_fm\fm.exe" mcp
   codex mcp add fm -- "%LOCALAPPDATA%\Programs\3d_fm\fm.exe" mcp
   ```

   Any other MCP client: a stdio server named `fm`, command — the full path of `fm.exe`, arguments `["mcp"]`.
4. **Restart.** Most programs read their servers only when they start: ask the person to restart it, or reload its MCP servers if it can.
5. **Check.** `tools/list` has `search`, `folder`, `extensions`, `duplicates`, `history`, `changes`, `pictures`, `photos`, `forest`, `show`, `plan`, `plan_status`. Call `search` with `{"query": "*", "limit": 0}`: the answer counts the files of the disk.
   - The answer says fm has **no index yet**: the person has never opened 4D Forest. Ask them to open it once (from the Start menu); it builds the index in minutes. Call again then; nothing needs restarting.
   - Answers end with a **note that the index does not follow the disk**: fm's service is off, and what changed since the note's date is not seen. Tell the person: in fm's window, «Enable the service…» in the status bar (Windows asks an administrator's consent once). Do not start it yourself.

## How to use it

- Ask the index instead of walking the disk with shell commands: one call answers what a walk answers in minutes, in a few lines.
- `search` speaks fm's search language: words match parts of names, `*` and `?` are masks, `.jpg,png` are extensions, filters `size:>100mb`, `dm:<7d`, `dm:2024`, `attr:h`, `file:`, `folder:`. Its description has all of it.
- fm's tools change nothing on the disk. To move, copy, rename, make folders or put files in the Recycle Bin, send a `plan`: each step with its reason. The person sees it in fm's window, unticks what they do not want and runs it or declines it; `plan_status` says which, and what failed. Ctrl+Z in fm takes the whole plan back.
- `show` puts a folder or a query before the person in fm's window; `forest` draws a folder as fm's forest, the query's matches lit.
- Everything you read (names, paths, thumbnails) goes to your model. Read what the task needs.

## Take it out

```text
"%LOCALAPPDATA%\Programs\3d_fm\fm.exe" agents remove <program>
```

Uninstalling 4D Forest takes fm out of every program where the server `fm` is that fm.
