Skip to Content
AI assistantsSetup guide

Connect an AI assistant to DupliWalker Desktop

This guide has setup steps for connecting an AI assistant on your Mac to DupliWalker Desktop, for Claude Code, Codex and Claude Desktop. Deltopia has not yet checked these steps in each of those clients: each client’s section says what has been checked, and where it has not, the steps follow that client’s own documentation. claude.ai and ChatGPT in a web browser cannot connect, because a web page cannot start a program on your Mac, and the guide does not apply to DupliWalker for the web. For what the connection is and why you stay in control, see the overview.

The whole job is seven steps:

  1. Install DupliWalker Desktop 1.0.0-beta.5 or later. During the public beta you need no particular edition and no licence; step 2 says what the beta and release builds each need.
  2. Turn on Allow AI agents to run automation scripts (MCP) in the app.
  3. Add DupliWalker to your assistant.
  4. Check that the assistant is connected.
  5. Ask it for a first task.
  6. Approve the script in DupliWalker.
  7. Later: remove the connection, or turn access off.

Step 1: Install DupliWalker Desktop

  1. Download DupliWalker Desktop for Mac with Apple Silicon and move it to your Applications folder. You need version 1.0.0-beta.5 or later. Earlier builds have no MCP launcher.
  2. Know what the connection needs. During the public beta, every feature is unlocked for every user, including this connection, until 1 de febrero de 2027 a las 00:00 UTC, with Pro or with no licence. The beta build expires then; it does not switch to licence-based access, and you will need a newer DupliWalker build. Separately, as the release-build policy: MCP scripts count as custom automation, and in release (non-beta) builds this connection needs Oro or the Trial: Pro does not include custom automation, and a script is refused with “This edition does not include running custom automation scripts, so the script was not run.”
  3. Check that the launcher is there. In Terminal:
ls -l "/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp"

If it says “No such file or directory”, you have an older build or DupliWalker is somewhere else. See If DupliWalker is installed somewhere else and Troubleshooting.

Step 2: Turn on AI agent access

  1. Open DupliWalker Desktop.
  2. Click the gear icon at the top right of the window. The Application Settings dialog opens.
  3. In the dialog, make sure the Application tab is selected, choose General, and find the AI agents section.
  4. Turn on Allow AI agents to run automation scripts (MCP).

The short form used in the rest of this guide is Settings › General › AI agents.

It is off by default, and it is only in the desktop app. Until it is on, the launcher cannot reach the app.

Step 3: Add DupliWalker to your assistant

The server is called dupliwalker in every example, so the assistant’s tools show up as dupliwalker’s tools. Pick your assistant.

Claude Code

Add it once for your user account, so it is there in every project:

claude mcp add --scope user dupliwalker -- "/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp"

The -- separates Claude Code’s own options from the program it starts. Everything after it is passed to the launcher untouched.

  • Checked by Deltopia, Claude Code: Not yet checked — steps follow Claude Code's documentation

To share it with one project only, put it in a .mcp.json file at the project’s root instead. Claude Code asks you to approve a project’s servers before it uses them:

{ "mcpServers": { "dupliwalker": { "command": "/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp" } } }

A .mcp.json is usually committed to version control, and the path in it is a path on your Mac. Keep it out of a shared repository unless everyone installs DupliWalker in the same place.

Codex

These steps are for the Codex command line. They follow OpenAI’s documentation, which describes ~/.codex/config.toml as its MCP configuration.

  • Checked by Deltopia, Codex (command line): Not yet checked — steps follow Codex's documentation

Either add it with a command:

codex mcp add dupliwalker -- "/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp"

or add it to ~/.codex/config.toml yourself:

[mcp_servers.dupliwalker] command = "/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp"

Codex can also read a .codex/config.toml inside a project, for trusted projects only. Use that only if you want the connection for that project alone.

Claude Desktop

  • Checked by Deltopia, Claude Desktop: extension: Not yet checked — steps follow Claude Desktop's documentation
  • Checked by Deltopia, Claude Desktop: manual configuration: Not yet checked — steps follow Claude Desktop's documentation

With the extension. Download dupliwalker-1.0.0.mcpb and install it in one of the two ways Anthropic documents: double-click the file, or choose Settings › Extensions › Advanced settings › Install Extension in Claude Desktop and pick the file. The extension finds the installed DupliWalker app and starts its launcher. If DupliWalker is not in your Applications folder, set the extension’s DupliWalker app location setting.

The extension file is not code-signed. Download it only from this page.

By hand. Add this to Claude Desktop’s configuration file, ~/Library/Application Support/Claude/claude_desktop_config.json. If the file already has an mcpServers section, add only the dupliwalker entry inside it:

{ "mcpServers": { "dupliwalker": { "command": "/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp" } } }

An extension or a configuration you install by hand does not update itself. After you update DupliWalker, check that the path still exists; after a new version of the extension is published, install it again.

If DupliWalker is installed somewhere else

Replace /Applications/DupliWalker.app with the folder the app is really in. The launcher is always at Contents/Resources/bin/dupliwalker-mcp inside the app. Each syntax has its own rule:

  • Shell (claude mcp add, codex mcp add): keep the path in double quotes, because a space would otherwise split it into two words. A ~ is not expanded inside quotes; write $HOME instead, as in "$HOME/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp". The shell expands it before the command runs.
  • JSON and TOML (.mcp.json, claude_desktop_config.json, config.toml): write the full absolute path inside the quotes. Neither ~ nor $HOME is expanded there. A space needs no escaping.

If you start the app after the assistant

By default the launcher answers at once, and if DupliWalker is not running yet the connection fails. To make it wait for the app, give it a number of seconds with --wait. This waits up to a minute:

claude mcp add --scope user dupliwalker -- "/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp" --wait 60

In a configuration file the option goes in args:

{ "mcpServers": { "dupliwalker": { "command": "/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp", "args": ["--wait", "60"] } } }
[mcp_servers.dupliwalker] command = "/Applications/DupliWalker.app/Contents/Resources/bin/dupliwalker-mcp" args = ["--wait", "60"]

Step 4: Check the connection

Your assistant reads its server list when it starts. If you added DupliWalker while it was running, start a new session, or restart the app. Then check:

  • Claude Code: run claude mcp list in a terminal, or type /mcp in a session. dupliwalker should be listed as connected.
  • Codex: run codex mcp list, or type /mcp in the Codex terminal interface.
  • Claude Desktop: look for DupliWalker among your extensions or local MCP servers in Claude Desktop’s settings, then ask the assistant to list your DupliWalker windows. If you edited the configuration file, quit Claude Desktop completely and open it again first.

DupliWalker has to be running, with the setting from Step 2 on, for the check to pass.

Step 5: Try a first task

The three tools

The assistant gets three tools from dupliwalker:

  • list_windows lists the open DupliWalker windows: an id, the title, whether it has focus and when it was last focused. It changes nothing.
  • get_api_typings returns the declarations of DupliWalker’s automation API, and how a script is shaped. It changes nothing. An assistant should call it before it writes a script.
  • run_script runs a script in a window, after you approve it. It is marked as able to change things, because a script can.

Ask for it

Paste this to your assistant:

Use the dupliwalker MCP server. Call list_windows and tell me which window you will use. Then call get_api_typings for it. Then run a small read-only script, titled "First look", that logs how many duplicate groups the current results hold. Do not change anything.

The assistant should end up running a script like this one. It reads the current results and changes nothing:

export default async function (ctx) { const results = ctx.app.duplicateGroups; ctx.console.log(`Duplicate groups in the current results: ${results.count}`); const folders = results.folderGroups(); ctx.console.log(`Identical-folder groups: ${folders.groups.length}`); return { duplicateGroups: results.count }; }

A script is an ES module whose default export is an async function. It takes one argument, ctx, and ctx.app is DupliWalker. Output goes through ctx.console, and the assistant gets it back in the result along with the returned value. If you have not run a scan, the counts are zero.

More than one window

Without a window id, a script runs in the most recently focused DupliWalker window. If several are open, ask the assistant to call list_windows first and to say which window it picked, or tell it the title. Tools that act on a window take a windowId. A script in one window does not touch another.

Step 6: Approve the script

DupliWalker comes to the front and shows the script and a line “Requested by client via MCP”, with two buttons:

  • Allow Once runs the script this one time.
  • Deny runs nothing. Pressing Escape or clicking outside the dialog also denies it.

There is no “always allow”: the next script asks again. Read the script before you decide. It can use anything DupliWalker’s automation API offers, including actions that change or delete files. The assistant gets the result of the run, or the refusal.

Output goes to the assistant and to DupliWalker’s Automation output. Runs in one window go one at a time, so a second request waits for the first.

Step 7: Remove the connection or turn it off

Turn access off in DupliWalker. Turn off Allow AI agents to run automation scripts (MCP) in Settings › General › AI agents (the gear icon at the top right opens the dialog). It takes effect at once: DupliWalker closes the assistant’s session. If an approval dialog is waiting, it is closed and that script does not run. The assistant gets a connection error instead of a result, and until you turn the setting back on it cannot reconnect. The assistant’s entry stays in its configuration.

Remove DupliWalker from your assistant.

  • Claude Code: claude mcp remove dupliwalker. If you added it to a project’s .mcp.json, delete the dupliwalker entry there too.
  • Codex: delete the [mcp_servers.dupliwalker] table, and any args line under it, from ~/.codex/config.toml.
  • Claude Desktop: remove the DupliWalker extension in Claude Desktop’s extension settings, or delete the dupliwalker entry from claude_desktop_config.json and restart Claude Desktop.

Limits to know about

  • Scripts cannot import modules. Type-only imports are fine.
  • Output has to go through ctx.console. What the assistant gets back is capped at 1 MB, and returned values are made JSON-safe and size-capped.
  • Runs are one at a time per window.
  • A connection that has been idle for 30 minutes is dropped by DupliWalker. If your assistant then cannot use the tools, reconnect it (see Troubleshooting).
  • A script is limited to 524,288 characters, and its title to 200.

Troubleshooting

The launcher is missing, or the build is older

ls in Step 1 says the file does not exist. The launcher came with the version in Step 1; DupliWalker Desktop 1.0.0-beta.5 or later has it. Check the version in the About dialog (Help › About), download the current build from the download page and replace the app. If the app is not in /Applications, use the path where it is.

“DupliWalker is not running. Start it, then reconnect.”

The launcher found no running app that accepts connections. Check, in this order: DupliWalker is open; Allow AI agents to run automation scripts (MCP) is on (Step 2); then reconnect from your assistant (/mcp in Claude Code, or a new session in Codex). If you want the connection to wait for the app, add --wait, as above. The launcher also gives this answer when MCP is off, because the app only offers the connection while it is on.

The setting is off

If the setting is turned off while an assistant is connected, DupliWalker closes the session. The assistant’s client gets the JSON-RPC error -32002, “DupliWalker closed the connection: the response stream ended before the app answered”, and the launcher exits with code 3. Reconnecting after that fails with -32001, “DupliWalker is not running. Start it, then reconnect.”, until the setting is back on. If a script request does reach the app while it is running with the setting off, it is refused with “AI agents are not allowed to run automation scripts in DupliWalker”, which tells you to turn on Allow AI agents to run automation scripts (MCP) in Settings › General. Turn the setting on, then reconnect.

“This edition does not include running custom automation scripts, so the script was not run.”

This refusal applies to release (non-beta) builds with a Pro licence: Oro and the Trial have the custom-automation right; Pro does not. During the public beta, until 1 de febrero de 2027 a las 00:00 UTC, every feature is unlocked, including this connection, so a beta build does not refuse a script for this reason. Nothing is wrong with the connection.

The script was denied or cancelled

The result says the script was not approved. You pressed Deny or Escape, or clicked outside the dialog. Ask the assistant to try again if you meant to allow it. It will ask for a new approval. If you turned the setting off while the approval dialog was open, the dialog is closed, the script does not run, and the assistant gets no result at all, only a closed connection (see “The setting is off” above).

The wrong window, or the wrong copy of the app

A script runs in the most recently focused window unless the assistant is given a window id. Ask it to call list_windows and name the window it uses. If more than one copy of DupliWalker is running, the launcher picks the newest. To pick one yourself, add --instance and the instance’s id to the launcher’s arguments, the same way --wait is added above. If a tool says “No DupliWalker window is open”, open a window.

DupliWalker quit or restarted

When the app quits, or access is switched off, the launcher exits and the assistant loses the connection. Start DupliWalker, make sure the setting is on, and reconnect from the assistant: /mcp in Claude Code, a new session in Codex, or a restart of Claude Desktop.

The assistant does not list DupliWalker

You started the session before you added the server, or the configuration has a typo. Start a new session. In Claude Code run claude mcp list; in Codex run codex mcp list. In a configuration file, check that the path exists, and that the quotes and commas are right.

Privacy

The connection is local, but what a script returns or logs goes to your AI assistant, and its provider processes that under its own terms. File names, paths and sizes are the kind of thing a DupliWalker script can see. Ask for the least that answers your question, and read what you approve.