Draft, 13 October 2026. Originally written by Christian Ferreira (revisions 1 to 6); revised by David Caress with Claude Code to match project practice.
This guide explains how MB-System developers use Claude Code, Anthropic's AI coding
assistant, on their own machines: how the project instructions are organized, how to
set up a build Claude can work with, how to work with Claude safely, and how
Claude-assisted work is reviewed, verified and disclosed. It covers the Claude desktop
app (Code tab), the claude terminal command, and Remote Control from the Claude app
or a phone.
The rules Claude actually follows are in the top-level CLAUDE.md. This guide
explains them and does not repeat them; if the two ever disagree, CLAUDE.md wins.
- Principles
- How project instructions are organized
- Example setup: macOS and Homebrew
- Other platforms
- Ways to run Claude Code
- Worktrees
- Working loop
- Documentation, ChangeLog and disclosure
- Commits and pull requests
- Permissions and guardrails
- Patterns that have worked
- Troubleshooting
- First-run checklist
- Sources
- A human developer supervises and reviews every change. Claude proposes, edits, builds and tests; the developer decides what is kept, committed and pushed.
- Claude never commits, pushes, opens pull requests or posts on GitHub without explicit approval for that action.
- Verification is real. Changes are built and tested (ctest, real data, other platforms where relevant), and reports say plainly what was not tested.
- AI assistance is disclosed in the ChangeLog and in commit messages (section 8).
- Upstream-synced code is respected. TRN (
src/mbtrn*), GSF (src/gsf) and vendored third-party code are edited only after asking (seeCLAUDE.mdsection A). - Code execution and data stay local. Claude Code runs on your machine. The conversation is sent to Anthropic, so do not paste proprietary or client survey data into prompts.
Claude Code reads instruction files at the start of every session:
| File | Committed | Contents |
|---|---|---|
CLAUDE.md (top level) |
Yes | Shared project rules: architecture, build and test policy, conventions, upstream-synced code, ChangeLog and commit rules |
CLAUDE.local.md (top level) |
No (git-ignored) | Your own setup: paths, install prefix, remotes, build options, where your notes go, your preferences |
src/<dir>/CLAUDE.md |
Yes | Optional rules that load only when Claude works in that directory |
~/.claude/CLAUDE.md |
No | Your rules for all projects |
.claude/settings.json |
Yes | Shared permission rules (deny rules for destructive commands) |
.claude/settings.local.json |
No (git-ignored) | Your own permission allow-list, built up as you approve commands |
Notes:
- Put only what Claude cannot work out from the code. Keep each file under about 200
lines (
wc -l CLAUDE.md). - Your
CLAUDE.local.mdoverrides the shared file for your sessions. For example, a developer who builds with-DbuildTRN=OFFsays so there, so Claude knows not to claim TRN was tested. - Example
CLAUDE.local.mdfiles exist for the maintainer's setup and for the macOS sandbox setup in section 3. Ask either author for a copy. /contextin a session shows which files were loaded. After editingCLAUDE.mdmid-session, tell Claude to re-read it.- Claude Code also keeps its own memory across sessions. It is useful for personal
context, but project rules that every contributor needs belong in
CLAUDE.md. - The repository
.gitignoreexcludesCLAUDE.local.md,.claude/settings.local.json,.claude/worktrees/and other runtime files. Never commit them.
This is one complete, tested setup: macOS Tahoe 26 or later, Apple Silicon, Homebrew
only, everything under ~/sandbox so no sudo is needed. Other layouts work just as
well (for example the maintainer installs into /usr/local); record yours in
CLAUDE.local.md.
Homebrew 6 requires third-party taps to be trusted before their code runs, hence
brew trust.
brew update
brew tap dwcaress/mbsystem
brew trust dwcaress/mbsystem
brew install cmake pkg-config fftw gdal netcdf gmt proj libx11 libxt openmotif opencv qt@6 vtk
brew install dwcaress/mbsystem/mb-mesa
brew install dwcaress/mbsystem/mb-mesa-glu
cpan Parallel::ForkManager # needed by mbm_multiprocess, mbm_multicopy, mbm_multidatalistThe tap supplies mb-mesa and mb-mesa-glu, private kegs with a pinned Mesa version.
openmotif, libx11 and libxt are needed for the GUI programs, opencv for the
photomosaicing tools, and qt@6 and vtk only with -DbuildQt=ON.
Optional, for the documentation targets:
brew install pandoc weasyprint groff # htmldocs also needs perlDo not keep MacPorts (/opt/local) on your PATH: it can pull in the wrong GMT,
GDAL, PROJ or netCDF.
~/sandbox/MB-System # git clone
~/sandbox/MB-System/build # CMake build dir (in-source builds are refused)
~/sandbox/mbsystem # install prefix
~/sandbox/otps # OTPS tidal prediction install
~/sandbox/testdata # small sample files per format (read-only)
~/sandbox/out # scratch outputs and session notes
~/sandbox/MB-System-base # optional: git worktree of master for baseline comparison
~/sandbox/mbsystem-base # optional: baseline install prefix
Keep the clone outside iCloud Drive, Dropbox and similar sync folders; they can
corrupt .git.
Contributors work from a fork:
git clone git@github.com:<you>/MB-System.git ~/sandbox/MB-System
cd ~/sandbox/MB-System
git remote add upstream https://github.com/dwcaress/MB-System.git
git fetch upstream
git checkout -b dev/<topic> upstream/masterMaintainers with write access work on topic branches of the main repository and merge by pull request.
cd ~/sandbox/MB-System
mkdir -p build && cd build
cmake .. -DmacosUseMbMesa=ON \
-DMBMESA_PREFIX=/opt/homebrew/opt/mb-mesa \
-DMBMESAGLU_PREFIX=/opt/homebrew/opt/mb-mesa-glu \
-DCMAKE_INSTALL_PREFIX=$HOME/sandbox/mbsystem \
-DotpsDir=$HOME/sandbox/otps
make -j"$(sysctl -n hw.ncpu)" 2>&1 | tee build.log
ctest --output-on-failure
make install # prefix is under $HOME: no sudoUse $HOME, not ~, inside -D arguments: the shell does not expand ~ in the
middle of a word. If an earlier sudo make install left root-owned files, run
sudo chown -R $USER ~/sandbox/mbsystem once yourself.
| Flag | Purpose |
|---|---|
-DCMAKE_INSTALL_PREFIX |
Install location; the default is /usr/local |
-DotpsDir |
OTPS location; defaults to /usr/local/src/otps, so omitting it silently uses the wrong path |
-DmacosUseMbMesa=ON |
Use the private mb-mesa and mb-mesa-glu kegs for OpenGL |
-DMBMESA_PREFIX, -DMBMESAGLU_PREFIX |
Keg locations. If omitted, CMake asks brew --prefix; it stops with an error if a prefix does not exist |
-DbuildTRN=OFF |
Optional: skip the TRN directories. If you use it, say so in CLAUDE.local.md |
mb-mesa-glu is built against mb-mesa's own libGL. Mixing it with the standard
Homebrew GLU loads two libGL images in one process, GLU calls silently do nothing, and
the mbgrdviz 3D view goes blank. Always use the two kegs together.
| Option | Default | Use |
|---|---|---|
CMAKE_BUILD_TYPE |
Release | Debug for lldb sessions (use a separate build dir) |
BUILD_SHARED_LIBS |
ON | Shared vs static libraries |
buildGUIs |
ON | OFF skips mbview, mbedit, mbgrdviz, mbeditviz, mbnavedit, mbvelocitytool |
buildOpenCV |
ON | OFF skips the photomosaicing tools |
buildGSF |
ON | OFF removes GSF format support |
buildTRN |
ON | OFF skips the TRN tools |
buildTests |
ON | Configures the test/ suite run by ctest |
buildQt |
OFF | Qt GUIs (VTK 9.3 or later) |
buildPCL |
OFF | Point-cloud-library tools |
buildDeprecated |
OFF | Deprecated programs |
CMake always writes build/compile_commands.json, which is also used for the
MinGW-w64 cross-check (section 4).
export PATH=$HOME/sandbox/mbsystem/bin:$PATH
gmt gmtset GMT_CUSTOM_LIBS $HOME/sandbox/mbsystem/lib/mbsystem.dylib- CMake sets the RPATH; do not set
DYLD_LIBRARY_PATH(macOS strips it anyway). - GMT needs the MB-System plug-in for
gmt mbcontour,mbswath,mbgrdtiffandmbgrd2obj. - GMT reads
gmt.conffrom the current directory first. A crashed script can leave an orphangmt.confthat silently changes later runs. - Another MB-System on your
PATH(a Homebrewmbsystem, an old/usr/localinstall) can shadow your build. Checkwhich mbinfo.
For before/after comparisons, build an unmodified master in a separate worktree with
the same options and its own prefix:
git worktree add ../MB-System-base upstream/master
cd ../MB-System-base && mkdir -p build && cd build
cmake .. <same options> -DCMAKE_INSTALL_PREFIX=$HOME/sandbox/mbsystem-base
make -j"$(sysctl -n hw.ncpu)" && make installThen run a tool from both prefixes on the same scratch copy of the data and diff the text output. Treat the baseline worktree as read-only: do not edit it or start a Claude session in it.
- Linux: install the equivalent distribution packages (see
BuildAndInstall.md) and configure without the macOS Mesa options. The build must keep working on older glibc (before 2.34) as well as current distributions. - Windows (MinGW-w64): supported for the non-GUI programs. Changes to portable
code or build files should be checked with a MinGW-w64 cross-compile. A quick
check from macOS or Linux: from a scratch build, take each command in
compile_commands.json, run it withx86_64-w64-mingw32-gcc/g++ -fsyntax-only, pass host include directories (e.g./opt/homebrew/include) as-idirafter, and addsrc/mbaux. Claude can script this. - MSVC: not a supported target and usually not testable. Accept MSVC fixes only when they do not break MinGW-w64, and say in the commit that MSVC was not tested.
- Autotools: still maintained alongside CMake. New files go into
Makefile.amas well asCMakeLists.txt; regeneratingconfigureis left to the maintainer.
| Mode | How | Good for |
|---|---|---|
| Desktop app, Code tab | Open the repository folder in the Claude desktop app | Day-to-day work; diff, terminal and browser panes; app-managed worktrees for parallel sessions |
| Terminal | cd ~/sandbox/MB-System && claude |
Working alongside your own shell |
| Remote Control | claude remote-control, or /remote-control (/rc) inside a session |
Steering a session on your Mac from the Claude app or a phone, e.g. during long builds |
Requirements: a Pro, Max, Team or Enterprise plan, signed in with a claude.ai account
(/login). The first run in a directory asks you to trust it.
Remote Control connects claude.ai/code or the Claude mobile app to a session running
on your Mac. Execution and file access stay local; the transcript passes through
Anthropic's servers. Your Mac must stay awake and the claude process running.
- Suggested start:
claude remote-control --name "MBS: <topic>" --spawn same-dir. --spawnacceptssame-dir(default),worktreeandsession;--capacity Nlimits concurrent sessions. Other flags change between versions: checkclaude remote-control --help.- Unavailable if
ANTHROPIC_BASE_URLpoints elsewhere, with Bedrock, Vertex or Foundry, or withCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICset. - Run
caffeinate -dimsin another terminal for long jobs; a full build stalls while the Mac sleeps. - From the phone,
/compact,/clear,/context,/modeland/renamework;/resumeand/pluginare local only. Permission prompts wait until you answer. You can attach a screenshot, e.g. of a bad swath plot.
Several mechanisms create git worktrees. Each is a separate checkout that needs its own build directory.
| Desktop app / Remote Control worktrees | Baseline worktree (optional) | |
|---|---|---|
| Created by | Claude Code, per session (.claude/worktrees/, branch claude/<name>) |
You, once, with git worktree add |
| Purpose | Let parallel sessions edit without colliding | Unmodified master build for comparisons |
| Claude may edit it | Yes | Never |
Rules:
- Two sessions installing into the same prefix overwrite each other's files. Install from one session at a time, or give each its own prefix. Do not install from a worktree into the prefix you use for real data processing without deciding to.
- The desktop app can merge the base branch into a worktree for you; ask Claude to sync when a worktree falls behind.
- When several sessions or agents have edited code, do one full build of the combined result. Each agent's report that its own edit is fine is not proof that the whole build works.
- Clean up finished worktrees; uncommitted work in a removed worktree is lost.
- Investigate. Use plan mode (Shift+Tab) for read-only work. Claude confirms
the file is compiled, finds call sites, reads the nearest sibling driver or
program and its man page, checks history (
git log -S,git blame), reproduces with real data where possible, and proposes a minimal patch plus a verification plan. - Approve, then edit. For audits or large reviews, ask for findings first, in batches (e.g. five files at a time), and approve fixes per batch.
- Build and test. Full build with no new warnings, then
ctest --output-on-failure. If a test fails because of an intended change (e.g. new usage text), the test is updated and the reason stated; tests are never deleted or weakened to pass. - Check real data. Run the affected programs on a scratch copy of real files. For format work, compare against an independent source (another format from the same survey, vendor-computed soundings). Optionally diff against a baseline build.
- Check other platforms when portable code or build files changed (section 4).
- Document (section 8), then commit when you decide to (section 9).
Keep session notes, investigation logs and standalone patches outside the repository
tree (the location goes in CLAUDE.local.md).
- Every user-visible change updates the program's man page (
src/man/man1), its-Husage text and its long-option table together. ChangeLog.mdand the version number (MB_VERSIONandMB_VERSION_DATEinsrc/mbio/mb_define.h) are normally maintained by the maintainer. Contributors put ChangeLog-style text in their pull request description instead, unless asked.- The version and date rules, entry style and regeneration steps are in
CLAUDE.mdsection E. In short: the next beta after the latest one published on GitHub, today's date, the same in all three places, prose paragraphs per component, andChangeLog.html/.pdfregenerated (changelogtarget) and committed withChangeLog.md. src/htmlis regenerated with thehtmldocstarget, which rewrites many large files. Do it only on purpose.- Disclosure. Claude-assisted work is disclosed in two places:
- the ChangeLog: one short statement per release entry, after the Claude-assisted paragraphs, for example "The above work was done with the assistance of the AI coding assistant Claude Opus 5.5 (Anthropic, model claude-opus-5-5), operating as Claude Code under developer supervision and review.", naming the model actually used. Notes for work done without Claude go below it;
- the commit message: the same statement, plus the
Co-Authored-By:trailer that Claude Code adds.
- Commit only on a topic branch, never directly on
master. Stage explicit paths only. - Commit messages follow the project style: a short plain subject line, then prose paragraphs per component (matching the ChangeLog entry), then how the change was verified and what was not tested, then the disclosure paragraph.
- Claude shows the message and
git diff --cached --statand waits for approval. Pushing, opening a pull request and commenting on GitHub each need separate approval. - Contributors working from a fork rebase on
upstream/masterbefore opening a pull request. If the rebase changes anything, rebuild and re-verify before pushing. - When reviewing someone else's pull request, Claude can test it on platforms the author could not (e.g. MinGW-w64 for an MSVC-oriented change). Adopting part of a pull request is fine; say so in the commit message and credit the author.
Shared deny rules can go in .claude/settings.json (committed). Allow rules are
personal and accumulate in .claude/settings.local.json as you approve commands.
Starting point for the shared file; check the current permissions documentation for
exact syntax:
{
"permissions": {
"deny": [
"Bash(git push --force:*)", "Bash(git push -f:*)",
"Bash(git reset --hard:*)", "Bash(git clean:*)",
"Bash(sudo:*)", "Bash(rm -rf:*)", "Bash(make uninstall:*)"
]
}
}- Deny rules take precedence over allow rules. Matching is by command prefix, so
CLAUDE.mdalso states these rules in words to cover variants. - Avoid "bypass permissions" modes on a machine that holds survey data.
- Review each permission prompt; approving "always allow" adds a rule to your local settings file.
- Audits in batches. Memory-safety reviews of
src/utilitiesand the GUI editors went file by file, smallest first, five files per batch, findings reported before fixes. Recurring bug families (unchecked reallocations, unbounded string copies, unvalidated counts from files) were then searched for everywhere. - Evaluating an external pull request. The Windows build pull request (#1603) was cross-compiled with MinGW-w64, its platform-independent parts adopted, and the MSVC-only parts that broke MinGW-w64 left out, all explained in the commit.
- Validating format changes against independent data. kmall changes were checked against GSF from the same survey and against Kongsberg's own soundings after raytracing.
- Recording design decisions. When a session settles a design question (for
example: navigation passed through MBIO is that of the mapping sensor, not the
vessel reference point), add it to
CLAUDE.mdso later sessions and other contributors follow it. - Stale tests vs regressions. When tests fail after an intended change, compare the actual program output with the test's expectation before assuming a regression.
| Symptom | Likely cause and fix |
|---|---|
| Test failures after changing options or usage text | Test assertions expect the old text; update them and explain |
CMake fatal error about MBMESA_PREFIX or MBMESAGLU_PREFIX |
Kegs not installed; install from the dwcaress/mbsystem tap |
brew install dwcaress/mbsystem/... refuses to run |
Tap not trusted; brew trust dwcaress/mbsystem |
| "In-source builds are not allowed" | cmake ran in the repo root; remove CMakeCache.txt and CMakeFiles there |
| OTPS tools cannot find OTPS | -DotpsDir omitted; reconfigure with it |
A directory literally named ~ appears |
~ used inside a -D argument; use $HOME |
| Wrong libraries picked up | /opt/local on PATH or a stale cache; rebuild from an empty build dir |
mbinfo reports a different version |
Another install on PATH; call your prefix's bin/mbinfo |
gmt mbswath not found |
GMT_CUSTOM_LIBS not set to your mbsystem.dylib |
| mbgrdviz 3D view blank | Mixed Mesa; use mb-mesa and mb-mesa-glu together |
| Root-owned files in your prefix | Earlier sudo make install; sudo chown -R $USER <prefix> |
| Claude ignores a rule | Check /context; ask Claude to re-read CLAUDE.md |
| Nothing happens during a long build | A permission prompt is waiting, or the Mac is asleep |
claude remote-control exits with an error |
Not signed in with a claude.ai account; /login |
| Session not listed in the app | Different account, or a base URL override is set |
- Install the prerequisites for your platform (section 3 or 4).
- Clone the repository (or your fork) and configure, build and install. Run
ctest. - Write your
CLAUDE.local.md: paths, prefix, remotes, build options (especially anything that differs from the defaults, such asbuildTRN=OFF), where session notes go. - Open the repository in the Claude desktop app or run
claude, and check with/contextthatCLAUDE.mdandCLAUDE.local.mdwere loaded. - Put a few small sample files per format somewhere read-only.
- Try a trivial change (e.g. a man-page typo) through the whole loop: investigate, edit, build, test, document, commit on a topic branch.
- Only then move to real work.
- Claude Code documentation: https://code.claude.com/docs
- Memory and CLAUDE.md: https://code.claude.com/docs/en/memory
- Permissions: https://code.claude.com/docs/en/permissions
- Remote Control: https://code.claude.com/docs/en/remote-control
- Best practices: https://code.claude.com/docs/en/best-practices
- Homebrew tap trust: https://docs.brew.sh/Tap-Trust
- MB-System installation: https://www.mbari.org/technology/mb-system/installation/
and
BuildAndInstall.md - MB-System repository: https://github.com/dwcaress/MB-System