Troubleshooting

Mooring doesn't open

Symptom: You double-click Mooring and nothing happens, or its icon bounces and disappears.

A download that was cut short can leave a damaged copy. To fix it:

1. Download Mooring again from mooring.sh/download.
2. Drag the new copy into your Applications folder, and replace the old one.

Install Mooring from the download or with Homebrew, rather than copying the app from another Mac.

Mooring doesn't update

Mooring updates itself. To check for an update now, choose Mooring ▸ Check for Updates…. If no update appears:

• Make sure your Mac is running macOS 26 or later.
• Some work networks block downloads. Try another network.

macOS asks about "data from other apps"

Symptom: macOS asks whether Mooring may access data from other apps, or shows a "Data Access Blocked" notification.

Claude sometimes searches your whole disk, and macOS guards other apps' private folders. Because the search started in Mooring, macOS names Mooring. Give Mooring Full Disk Access to let these searches through:

1. Open Settings ▸ General ▸ Full Disk Access in Mooring.
2. Click Open Full Disk Access Settings….
3. Turn on the switch next to Mooring.

Access works straight away. No restart needed.

Screen capture doesn't work

Claude can capture the screen through Mooring's tools. macOS gives that permission to Mooring itself.

1. In Mooring, open Settings ▸ MCP and turn on Allow screen capture. macOS asks for Screen Recording permission.
2. In System Settings ▸ Privacy & Security ▸ Screen Recording, make sure Mooring is turned on. If tmux is listed there, you can remove it. Mooring doesn't use it.
3. Quit Mooring and open it again. macOS uses a new Screen Recording permission only when the app next opens. Your sessions keep running if you choose Keep Running.

A Claude tab doesn't have Mooring's tools

Check these, in order:

1. The agent setup. Open Settings ▸ AI Agents, select the setup the tab started from, and turn on Mooring MCP tools.
2. The session. Right-click the tab and choose Restart Session. Claude resumes the same conversation, connected to Mooring's tools. The MCP status in the status bar also offers Restart Session with Mooring MCP for a tab that started without the tools.
3. The master switch. Open Settings ▸ MCP and make sure Let agents control Mooring is on.
4. Your organisation's policy. On Claude for Teams or Enterprise, an admin can block Mooring's MCP server. Settings ▸ MCP names the rule and what your admin needs to change. Restarting the session can't get around it.

Cloning, pushing or pulling fails

Mooring runs the git on your Mac, with the login your git already uses: the macOS Keychain, gh auth login, another credential helper, or your SSH key. Anything you can clone or push in Terminal, Mooring can too. Mooring never asks for or stores your password.

When something fails, Mooring says why and what to do next, for example no saved login, a server it couldn't reach, or work on the remote you need to pull first.

To check a project's connection:

1. Open Settings ▸ Git.
2. Under Connection, click Test. Mooring checks that it can fetch from and push to the project's remote. Nothing is sent.

If git isn't installed, or is older than 2.38, Mooring offers Install Command-Line Tools…. Settings ▸ Git also shows which git Mooring uses, and lets you choose another.

Coxswain says "Not logged in"

Coxswain uses Claude Code's login. Open a Claude tab, sign in with /login, then open Coxswain again.

Send a log with a bug report

Mooring writes a log to macOS's own log, under the subsystem sh.mooring. To save the last half hour to your Desktop:

1. Make the problem happen.

2. Within half an hour, run this in Terminal:

   /usr/bin/log show --last 30m --info \
     --predicate 'subsystem BEGINSWITH "sh.mooring" AND process == "Mooring"' \
     > ~/Desktop/mooring-log.txt

3. Attach mooring-log.txt to your report, and say roughly when the problem happened.

Type the full /usr/bin/log: in zsh, a plain log is a different command. The log keeps out what you type, but it does name your projects, branches and file paths, so read it before you post it anywhere public.

To read the log live, open Console and filter for messages whose subsystem begins with sh.mooring.