Setup

Install the app to start digging. This guide also covers Soulseek audio, Cosine Club recommendations and MCP mix research.

macOS installation

Download the disk image for your Mac: Apple silicon for an M-series Mac, or Intel. Apple menu → About This Mac shows your chip or processor.
In Finder, open Downloads and double-click the downloaded .dmg file. A disk image is a window containing the app.
Drag Auto Digger.app from that window into Applications. Wait for the copy to finish, then open Finder → Applications and double-click Auto Digger.

These preview builds are ad-hoc signed and not notarized. If macOS says it cannot verify the developer, use Apple's normal approval route:

After trying to open the downloaded app, open Apple menu → System Settings.
Choose Privacy & Security, scroll down and choose Open Anyway for Auto Digger.
Confirm Open when asked. Auto Digger should now open from Applications.

Apple's safe app-opening guide explains these messages. A warning that software will damage your computer is different; follow Apple's guidance rather than overriding it.

Terminal troubleshooting for the official Auto Digger download

If the trusted official preview still fails to open after the steps above, this project workaround removes the download quarantine label from Auto Digger's installed app bundle.

Open Terminal, the macOS app where you paste commands: press Command + Space, type Terminal and press Return. You can also find it in Finder → Applications → Utilities.
Copy the two lines below, click inside the Terminal window, paste, then press Return:

xattr -dr com.apple.quarantine "/Applications/Auto Digger.app"
open "/Applications/Auto Digger.app"

The second line opens Auto Digger. If you installed it outside Applications, move it there first so the address matches. Use this only for the official Auto Digger release you downloaded and trust.

Apple's Terminal guide

Soulseek audio

Choose Soulseek under Audio sources to search for a track and copy completed audio into your Auto Digger library. The guide covers native and Docker setup on macOS, Windows and Linux.

Soulseek setup guide

Cosine Club recommendations

Find tracks with a similar sound, preview suggestions and open linked Discogs releases from the digging desk. Add your Cosine Club key in Settings to get started.

Cosine Club setup guide

Connect your AI assistant

Your assistant can find the records in a mix and save them to a crate.

Open Settings → Auto Digger MCP in Auto Digger and choose Enable MCP. Then follow the steps for your assistant below.

Set this up once on the same computer. Keep Auto Digger open while using it. No separate Node installation is needed for MCP.

Claude Desktop

In Auto Digger, choose Save Auto Digger MCP. Save the file in Downloads.
In Claude Desktop, open Settings → Desktop app, choose Manage beside Extensions, then Advanced settings.
Choose Install Extension, select Auto Digger MCP.mcpb from Downloads and follow the prompts.

Claude runs the extension for you. You do not need to open a terminal or edit a configuration file.

Linux: use Claude Desktop's official beta for Ubuntu 22.04+ or Debian 12+. Install the saved file through Claude's settings as above. Linux installation help.

Claude extension installation help

Codex

In Auto Digger, expand Codex and other local clients to see the setup fields.
In Codex, open Settings → MCP servers → Add server. Name it auto_digger and choose STDIO.
Copy Command, then Argument 1, Argument 2 and Argument 3 into the matching fields. The values are ready to paste.
Add the environment variable ELECTRON_RUN_AS_NODE with value 1. Save and restart Codex.

Auto Digger supplies the runtime. Keep all three arguments in the order shown.

Codex configuration file

For Codex CLI, paste the complete block from Auto Digger into ~/.codex/config.toml. Replace an existing [mcp_servers.auto_digger] block. Preserve your other settings.

[mcp_servers.auto_digger]
command = "copy the command from Auto Digger"
args = ["copy the first argument", "--connection", "copy the last argument"]
env = { ELECTRON_RUN_AS_NODE = "1" }

Codex MCP help

Claude Code

Claude Code uses the same local connection. Its setup command is below.

Claude Code command

A terminal is the app where you paste command-line instructions. On Mac, press Command + Space, type Terminal and press Return. On Windows, open Start, type PowerShell and open it. On Linux, find Terminal in your app menu.

Use the executable and paths displayed in Auto Digger. A path is a file’s full address. Replace the examples below with those values, keep quotation marks around addresses containing spaces, paste the completed line into your terminal and press Return/Enter:

claude mcp add --transport stdio --scope user auto_digger --env ELECTRON_RUN_AS_NODE=1 -- "EXECUTABLE_FROM_SETTINGS" "FIRST_ARGUMENT_FROM_SETTINGS" --connection "LAST_ARGUMENT_FROM_SETTINGS"

Open Claude Code and use /mcp to check the connection.

Claude Code MCP help

Try a request

Start with: Use Auto Digger to list my crates.

For mix research, supply a real mix URL and ask:

Research this mix. Find the original Discogs releases, save them to a Mix picks crate and mark the matching tracks. Keep source links and flag uncertain matches.

Your AI client researches the sources and judges recording matches. Auto Digger verifies Discogs metadata and saves the results. Check the picks and any uncertain matches in Crates.

Tools and research details

Troubleshooting

My assistant cannot connect: Open Auto Digger and choose Enable MCP. Do this each time you reopen the app. Restart your assistant if its tools have not appeared.
Search does not work: Check that Discogs is connected in Auto Digger. Your Discogs token stays in the app.
I moved or updated Auto Digger: Copy fresh Codex configuration if its paths changed. This can also happen when running a Linux AppImage. The Claude extension keeps its own copy of the helper.
Claude refuses the extension: Update Claude Desktop and try saving the extension again. Work accounts may need an administrator to allow custom extensions.