Home

Every reading this machine has kept can be served over the Model Context Protocol, so an agent works from findings that have already been validated instead of re-deriving them through a cluster connection. The server holds no kubeconfig — there is no client-go in that binary and a test walks its imports to keep it that way — so an agent holding it can read the corpus and cannot touch anything.

Needs a Team licence, and shoalcheck-mcp from the command-line download — the macOS app does not carry it.

claude mcp add shoalcheck -- shoalcheck-mcp
shoalcheck-mcp --cluster prod      # serve one cluster's newest reading
shoalcheck-mcp --print-identity    # say which reading it would serve, then exit

Needs a Team licence. It works in this window, from any kept reading.

A finding becomes a ticket from the Queue tab of any reading: title, body, a dedup key, the labels, the engine's own safety verdict, and any compliance term the finding's own text cites — named out loud, because it travels verbatim while the report's control mapping does not.

Nothing is filed. Creating an issue in your workspace needs a credential this window does not hold, and an object in somebody else's tracker is not a read-only tool's to make. You get the text a push would have sent — read it, then paste it.

GitHub and GitLab code scanning both read SARIF, so a reading can annotate a diff without anything of ours running in your pipeline. The findings arrive as results with their rule, severity and evidence; a cost finding travels without its monthly figure, because SARIF has no field for one.

Needs the command-line download in your pipeline — the macOS app does not carry it — with a Pro licence for the SARIF file and a Team licence for the gate.

shoalcheck audit --context prod --export-sarif shoalcheck.sarif --no-tui   # read, then write the log
# then, in your workflow:
#   uses: github/codeql-action/upload-sarif@v3
#   with: { sarif_file: shoalcheck.sarif }
shoalcheck gate --context prod --baseline baseline.json   # fail the job when something new and high appears

Or write the same file from any kept reading under Handoff in that reading's workspace, here in the window.

Needs a Pro licence. It works in this window.

Written beside the reading, on this machine. Choose a reading under Readings and open Handoff to write one.

Needs a Team licence, and the command-line download on this machine: a schedule runs the shoalcheck command, found beside the app or on your PATH, and the macOS app does not carry it.

There is no telemetry and no crash report: nothing about a run leaves this machine. When a figure looks wrong, this file holds what is needed to reproduce it — and nothing about the cluster it read.

If this window will not start, the command line writes the same file: shoalcheck support, with --input reading.json to describe a reading.

A cluster is missing from Clusters

The list is every context in your kubeconfig. A context added while the window is open appears the next time it is opened.

It cannot sign in to a cluster

Settings → What this program may do lists the sign-in plugins your kubeconfig names (kubelogin, aws, gcloud…) and whether each was found. Install the missing one where your shell finds it and open the window again: it reads the PATH of your login shell.

A kind reads “refused”

The cluster said no to get or list on that kind for your identity. The reading says so where it matters and the rules that need the kind do not run. A role granting get and list on it is the fix — deploy/rbac.yaml in the command-line download is the role this program needs, and shoalcheck audit --show-permissions lists what an identity can read.

The licence key is rejected

The line under the key says why: not the whole key (paste it again exactly as it arrived), not signed by Shoalcheck, or ended — with its date. shoalcheck licence show says the same from a terminal.

A reading shows only its size, with a key installed

The key is bound to other clusters, or this machine has read as many clusters in 30 days as the plan covers; the result says which. Plan & licence → This copy reads a cluster's fingerprint and says whether the key covers it.

An update does not install

Settings → Updates says why. A folder you cannot write names the download; a copy Homebrew or krew installed updates with their own command.

You need the command line

The macOS app does not carry it. Download shoalcheck_<version>_<os>_<arch> from https://github.com/Shoalcheck/shoalcheck/releases — the same engine. The same page has shoalcheck-mcp and the kubectl plugin.

Where your files are

Readings, history, the licence and these settings: your home folder's .shoalcheck. While the window is open it also serves a copy of each reading from a temporary folder. Nothing about a cluster leaves this machine.

A question about one change does not need a whole audit. These read only the kinds the question needs and answer with an exit code a script can act on.