Set up your AI client for DeltaWalker Desktop

This guide has setup steps for connecting an AI assistant to DeltaWalker Desktop through MCP, for Claude Code, Codex and Claude Desktop, and takes you to a first task that the assistant runs after you approve it. 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. If you want to know first what this is and what it can do, start with Connect your AI assistant to DeltaWalker.

The steps:

1. Install DeltaWalker Desktop.
2. Turn on AI agents in DeltaWalker.
3. Add DeltaWalker to your AI client: Claude Code, Codex or Claude Desktop.
4. Check that it is connected.
5. Try a first task.
6. Approve the script.
7. Remove it, or turn it off.

If something does not connect, go to Troubleshooting.

1. Install DeltaWalker Desktop

Download DeltaWalker Desktop Beta 5 from the download page, open the disk image, and drag DeltaWalker into Applications. It needs a Mac with Apple Silicon and macOS 12 Monterey or later.

You need no licence: during the beta nothing in DeltaWalker Desktop is locked.

If you choose Keep Both in Finder because DeltaWalker Classic is installed as DeltaWalker.app, Finder names the new copy DeltaWalker 2.app, and the paths below change. See If DeltaWalker is not in Applications.

Check that your copy includes the connection program. In Terminal:

ls -l "/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"

It should list the file. This file, deltawalker-mcp, is the launcher: the program your AI client starts. If Terminal says “No such file or directory”, read The launcher is missing.

2. Turn on AI agents in DeltaWalker

1. Open DeltaWalker 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 rest of this guide calls this place Settings > General > AI agents.

It is off by default, and the setting exists in DeltaWalker Desktop only. While it is off, your AI client cannot connect: it sees “DeltaWalker is not running.”

3. Add DeltaWalker to your AI client

Every client below starts the same launcher. In each, the server’s name is deltawalker.

The default launcher path is:

/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp

Use it as it is when DeltaWalker is in Applications. If it is somewhere else, see If DeltaWalker is not in Applications before you copy a command.

Claude Code

Run this once in Terminal. --scope user adds DeltaWalker to every project you open with Claude Code:

claude mcp add --scope user deltawalker -- "/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"

The -- separates Claude Code’s own options from the launcher, and the quotes keep the path in one piece. Start a new Claude Code session so that it picks the server up.

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

Scopes. Without --scope, Claude Code uses local: the server is yours, in the current project only. --scope user makes it yours in every project, and is the best fit for a personal Mac. --scope project writes it to a .mcp.json file in the project, to share with a team. You can write that file yourself:

{
  "mcpServers": {
    "deltawalker": {
      "command": "/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"
    }
  }
}

Claude Code asks you to approve a project’s .mcp.json before it uses it. Everyone who shares the file needs DeltaWalker Desktop in the same place.

Check and remove. claude mcp list shows the connection, and claude mcp get deltawalker shows how it is set up. claude mcp remove deltawalker removes it. If you added the same name in more than one scope, say which: claude mcp remove deltawalker --scope user.

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

Add DeltaWalker with one command:

codex mcp add deltawalker -- "/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"

Or write the entry yourself, in ~/.codex/config.toml:

[mcp_servers.deltawalker]
command = "/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"

In the file, command is the program alone, as one string, so the path needs no extra quoting. Put any option for the launcher in args, as a list of strings: args = ["--wait", "30"].

To set it up for one project only, put the same [mcp_servers.deltawalker] table in a .codex/config.toml file inside the project. Codex reads it only in trusted projects.

Check and remove. codex mcp list shows the configured servers. In the Codex terminal interface, type /mcp to see the active ones. To remove DeltaWalker, delete its [mcp_servers.deltawalker] table from the file, or add enabled = false to it to switch it off and keep the entry. codex mcp --help lists what your version of Codex can do.

Claude Desktop

Claude Desktop has two ways in. The extension keeps the launcher’s location in a setting. The manual entry is a few lines of JSON.

• 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

Install the extension. The extension is a small file, deltawalker-1.0.0.mcpb, that finds the DeltaWalker installed on your Mac and starts its launcher. It contains no copy of DeltaWalker.

The extension file is not code-signed. Download it only from this page, and compare its SHA-256 above with the file you downloaded: shasum -a 256 followed by the file’s path prints the checksum of the file.

1. Install the file in one of the two ways Anthropic documents: double-click the downloaded file, or open Claude Desktop and choose Settings > Extensions > Advanced settings > Install Extension… and pick the file. Menu names can differ a little between versions of Claude Desktop.
2. If DeltaWalker is not in Applications, set the extension’s DeltaWalker app location setting to where you installed it.

An extension installed from a file does not update by itself. When a new version of the file is published here, download it and install it the same way.

Or edit the configuration yourself. In Claude Desktop, choose Settings > Developer > Edit Config. That opens ~/Library/Application Support/Claude/claude_desktop_config.json. Add DeltaWalker under mcpServers:

{
  "mcpServers": {
    "deltawalker": {
      "command": "/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"
    }
  }
}

If the file already has an mcpServers section, add the "deltawalker" entry inside it, with a comma between entries, rather than a second mcpServers. Save, then quit Claude Desktop completely and open it again. A manual entry does not follow DeltaWalker if you move it: change the path yourself. Use one of the two ways, not both, or the assistant will see two DeltaWalker servers.

If DeltaWalker is not in Applications

Every command above names the launcher by its full path. If you installed DeltaWalker Desktop somewhere else, replace the beginning of the path, up to and including DeltaWalker.app. Three examples of where it might be:

• a personal Applications folder: /Users/yourname/Applications/DeltaWalker.app
• Finder’s Keep Both copy: /Applications/DeltaWalker 2.app, which has a space in its name
• an external drive: /Volumes/Tools/DeltaWalker.app

Each kind of file needs different quoting:

• Terminal commands (claude mcp add, codex mcp add): put the whole path in double quotes, as above, because a space would otherwise split it in two. A quoted ~ is not expanded, so write $HOME instead, which is expanded inside double quotes:

  claude mcp add --scope user deltawalker -- "$HOME/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"

• JSON files (.mcp.json, claude_desktop_config.json): the path is a JSON string. Write it out in full, with no ~ or $HOME, because a file does not expand them. A space needs no escaping. Run echo "$HOME" in Terminal if you need your home folder’s name.

  "command": "/Users/yourname/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"

• TOML (~/.codex/config.toml): the same, a full path in a double-quoted string.

  command = "/Users/yourname/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"

In JSON and TOML the path alone is command, and each option goes in args. Do not paste a whole Terminal command into either file.

Start your AI client before DeltaWalker

By default the launcher gives up at once if DeltaWalker is not running. If you often open your AI client first, add --wait, with the number of seconds the launcher should wait for the app to start:

claude mcp add --scope user deltawalker -- "/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp" --wait 30

In a JSON file, it is "args": ["--wait", "30"] beside command, and in TOML args = ["--wait", "30"]. Codex gives a server 10 seconds to start unless you set startup_timeout_sec in its table, so if you use --wait with Codex, raise that too. The wait helps only when the setting in step 2 is already on.

4. Check that it is connected

Open DeltaWalker with the setting on, then:

• Claude Code: run claude mcp list in Terminal, or /mcp in a session. deltawalker should be listed as connected.
• Codex: run codex mcp list, or type /mcp in the Codex terminal interface. deltawalker should be listed.
• Claude Desktop: look for DeltaWalker among your extensions or local MCP servers in Claude Desktop’s settings, then ask the assistant to list your DeltaWalker windows.

If a client reports a failure, go to Troubleshooting.

5. Try a first task

DeltaWalker gives your assistant three tools. A good request uses them in this order:

1. list_windows lists the open DeltaWalker windows: each one’s id, title, whether it has focus, and when it was last focused. This is how the assistant knows what it is talking to.
2. get_api_typings returns the declarations of DeltaWalker’s automation interface, with a short note on how a script is shaped. The assistant should read them before it writes anything, so that it uses only what exists.
3. run_script runs a script in one window. You see the script first and decide (step 6).

Open DeltaWalker, and try this. If you want something to look at, open any file or folder comparison first:

Use the DeltaWalker server. List the windows, tell me which one you will use, read its API typings, and then run a script that reports the comparisons open in that window. It must not change anything.

The assistant will call list_windows and get_api_typings, write a script, and call run_script, which asks you for approval.

The script

The script it writes should look much like this one. You can also ask the assistant to run this exact script. It reads what is open and changes nothing:

export default async function (ctx) {
    const comparisons = ctx.app.comparisons;
    ctx.console.log(`Open comparisons: ${comparisons.size}`);
 
    for (const comparison of comparisons.items) {
        const inputs = comparison.roles
            .map(role => `${role}: ${comparison.getInput(role)}`)
            .join(', ');
        const active = comparisons.active?.id === comparison.id ? ' (active)' : '';
        ctx.console.log(`${comparison.kind} comparison${active}, ${inputs}`);
 
        if (comparison.kind === 'file' && comparison.navigation.isSupported) {
            ctx.console.log(`  differences: ${comparison.navigation.position.count}`);
        }
    }
 
    return { openComparisons: comparisons.size };
}

What to notice:

• The shape. A script is an ES module whose default export is an async function. DeltaWalker passes it one argument, ctx, and adds no globals. ctx.app is the way into DeltaWalker, and ctx.app.comparisons is its comparisons.
• The output. Write output with ctx.console.log and its relatives, not the global console. What the script logs comes back to the assistant in the result, and so does the return value.
• Roles. A comparison’s sides are ref, one and, for a three-way comparison, two. ref is the Reference side.
• No imports. A script cannot import modules. Type-only imports are fine, because they disappear before the script runs.

When it finishes, the assistant gets a result that names the window the script ran in, and says whether you approved it and whether it succeeded or was cancelled. It also carries the return value, any errors and warnings, the console output, and how long the run took.

When you have several windows

The assistant should choose a window by its id, from list_windows, and pass that id to get_api_typings and run_script. Without an id, a script runs in the window that was most recently in front. The result always names the window it ran in, so check it. An id that does not belong to an open window is an error, and so is a request when no DeltaWalker window is open. If the assistant picks the wrong window, tell it which one you mean, by the window’s title, and ask it to list the windows again.

6. Approve the script

Each time the assistant calls run_script, DeltaWalker comes to the front and shows you:

• the script, in full, in a scrollable panel;
• who asked: Requested by client via MCP;
• two buttons, Deny and Allow Once.

Read the script before you choose. Allow Once runs this script and nothing else, and the next script asks again, because MCP has no “always allow”. Deny runs nothing and tells the assistant so. Pressing Escape or clicking outside the dialog also denies. If you are not sure what a script does, deny it and ask the assistant to explain.

Because a script can change things, such as merging a difference, saving a file or synchronizing folders, the script is what to review, not the request you typed. The setting in step 2 is the other half of the arrangement: with it off, nothing runs and nothing is shown.

7. Remove it, or turn it off

To stop an assistant using DeltaWalker without removing anything, turn off Allow AI agents to run automation scripts (MCP) in Settings > General > AI agents (the gear icon at the top right of the window opens the dialog). It takes effect at once: DeltaWalker closes the session. If an approval dialog is waiting, it is closed and that script does not run. Your client gets a connection error instead of a result, and cannot reconnect until the setting is back on. Turn it back on and reconnect your client when you want it again.

To remove DeltaWalker from a client:

• Claude Code: claude mcp remove deltawalker (add --scope user or --scope project if you added the name in more than one scope). For a project-scoped entry, you can also delete it from .mcp.json.
• Codex: delete the [mcp_servers.deltawalker] table from ~/.codex/config.toml (and from a project’s .codex/config.toml, if you added it there).
• Claude Desktop: uninstall the extension in Claude Desktop’s extension settings, or delete the "deltawalker" entry from claude_desktop_config.json and restart Claude Desktop.

Removing the entry from a client does not uninstall DeltaWalker Desktop or change its settings. The setting in DeltaWalker is the switch that cuts access for every client at once.

Limits to know about

• A script cannot import modules.
• Write output with ctx.console. DeltaWalker captures up to 1 MB of it per run.
• Scripts run one at a time in a window. A second request waits for the first.
• A connection that has been idle for 30 minutes is closed, and the client must reconnect.
• The value a script returns is made safe for JSON, and capped in size.
• A local connection does not keep your content on your Mac: whatever DeltaWalker returns to the assistant is processed by that AI client and its service. See the questions on the overview page.

Troubleshooting

The launcher is missing, or DeltaWalker is an older version

You see: “No such file or directory” for deltawalker-mcp, or your client says it cannot start the server.

Check:

ls -l "/Applications/DeltaWalker.app/Contents/Resources/bin/deltawalker-mcp"

If the file is not there, the copy of DeltaWalker you have is either an older build, from before MCP, or not DeltaWalker Desktop at all: DeltaWalker Classic has no launcher. Download DeltaWalker Desktop from the download page, replace your copy, and check again. If the app is installed under another name or in another place, such as DeltaWalker 2.app after Keep Both, use that path (If DeltaWalker is not in Applications).

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

You see: this message from the launcher, as a JSON-RPC error with code -32001.

Check: is DeltaWalker Desktop open? And is Allow AI agents to run automation scripts (MCP) on? The launcher gives the same answer when the app is closed and when the setting is off. Open the app, turn the setting on, then reconnect your client. To let the client start first next time, use --wait.

MCP is turned off

You see: the same “not running” message (code -32001) when the client connects. If the setting was turned off while a client was connected, that client instead gets a JSON-RPC error with code -32002, “DeltaWalker closed the connection: the response stream ended before the app answered”, and the launcher exits with code 3. Reconnecting then gives the “not running” message until the setting is back on. A script request that reaches the app while it is running with the setting off is refused with “AI agents are not allowed to run automation scripts in this app” and a note to turn the setting on.

Fix: turn on Allow AI agents to run automation scripts (MCP) in Settings > General > AI agents, and reconnect.

Licence or edition refusals

None apply to DeltaWalker Desktop Beta 5: nothing in the beta is locked, and this needs no licence. If you do see a message that your edition does not include running scripts, make sure you have the current DeltaWalker Desktop from the download page, and contact support if it persists.

A script was denied or cancelled

You see: a result with approved false and a refusal of denied or cancelled. Nothing ran.

What it means: denied means you chose Deny, pressed Escape, or clicked outside the dialog. cancelled means the request ended before it ran or while it ran, for example because the assistant withdrew it. Ask the assistant to run it again and choose Allow Once. Turning the setting off is different: it closes the approval dialog, the script does not run, and the client gets no result at all, only a closed connection (MCP is turned off).

The wrong window, or the wrong copy of DeltaWalker

You see: the result names a window you did not mean.

Fix: ask the assistant to call list_windows and pass the id of the window you mean to run_script, as in When you have several windows.

If you run more than one copy of DeltaWalker Desktop at the same time, the launcher connects to the newest one. Quit the copy you do not mean, then reconnect. The launcher also accepts --instance <id>, and the DELTOPIA_MCP_INSTANCE environment variable, to choose an instance by its id.

DeltaWalker quit or restarted

You see: tool calls fail after DeltaWalker was closed or updated, or after you turned the setting off.

Why: when DeltaWalker quits, or access is switched off, the launcher exits and the session ends. A connection also closes after 30 minutes idle. Your client does not reconnect to a new DeltaWalker by itself.

Fix: start DeltaWalker, make sure the setting is on, and reconnect the client.

Reconnecting your client

• Claude Code: run /mcp in the session and reconnect deltawalker, or start a new session.
• Codex: start a new session. In the Codex terminal interface, /mcp shows whether deltawalker is active.
• Claude Desktop: quit Claude Desktop completely and open it again.

The client does not list DeltaWalker at all

• Claude Code: claude mcp get deltawalker shows whether it exists and in which scope. A local entry applies only to the project you added it in. Add it again with --scope user.
• Codex: check ~/.codex/config.toml for typos in the table name or a missing quote, and run codex mcp list.
• Claude Desktop: check that claude_desktop_config.json is valid JSON, that the path is absolute, and that you restarted Claude Desktop. Do not use the extension and a manual entry together.

Still stuck? Contact support and say which client you use, what the launcher printed, and your DeltaWalker Desktop version.