# Claude Code

> Install the Stableship plugin: the MCP server, a /stableship:gate command, a skill, and hooks that bring the rules into every session.

Claude Code connects through the Stableship plugin. It brings:

- **The MCP server**, so Claude can read findings, fix briefs and rules, start checks and verify fixes.
- **`/stableship:gate`**, a command for the common jobs (below).
- **The `stableship` skill.** Claude loads it on its own before it changes sign-in, data access, payments or migrations: read the rules, give every new Supabase table row level security, keep the service-role key out of client code, and propose rule changes instead of making them.
- **Hooks.** At the start of a session Claude hears about open blocking findings. Before it edits a file about sign-in, data, payments or the database, it gets the rules for that file. Verdicts and new blocking findings arrive in the session as they land.

In a terminal, `npx --yes @stableship/cli@latest init` does both connect steps below in one go: it signs you in, and when the `claude` command is on that terminal's PATH it installs the plugin. When `claude` is not found, init signs you in and asks you to connect your agent; install the plugin with the first step below. Installing the plugin also removes a separate `stableship` MCP server you may have added before: the plugin brings its own, and with both, every tool is listed twice.

## Connect

1. Install the plugin in your terminal:

   ```sh
   claude plugin marketplace add stableship-ai/claude-plugins && claude plugin install stableship@stableship
   ```

2. Sign in, then approve in the browser:

   ```sh
   npx --yes @stableship/cli@latest login
   ```

The sign-in opens app.stableship.ai in your browser: sign in, pick the workspace and approve. No token to copy.

## Use a token instead

First make a token: in Stableship open **Settings**, then **Connections**, open **API tokens and connected apps**, and choose **Create token** with **Read findings and rules** and **Start checks and verify fixes**. Copy it: it starts with `sst_` and is shown once. Use it where these steps say `sst_your_token`.

Without the plugin, add only the MCP server with a token. Use the plugin or this, not both: both list every tool twice.

In your terminal:

```sh
claude mcp add --transport http stableship https://api.stableship.ai/mcp --scope user --header "Authorization: Bearer sst_your_token"
```

Keep the token out of your repository.

## Check it works

Open a new Claude Code session, or run `/clear`. Then ask Claude Code to list your Stableship projects: it calls `list_projects` and names your app.

If it does not connect:

- Run `/plugin`: Stableship should be installed and on.
- Run `/mcp`: Stableship should say connected.

## The /stableship:gate command

| Command | What it does |
|---|---|
| `/stableship:gate setup` | Signs in and connects this repository. |
| `/stableship:gate status` | The latest verdict and the blocking findings for this repository. |
| `/stableship:gate check [quick\|security\|qa\|full]` | Starts a check on your current branch, waits for the verdict and lists what blocks. Without a scope, the change decides. `--as <kind of user>`, `--flow <key>` and `--endpoint <path>` narrow it. |
| `/stableship:gate fix [findingId]` | For each blocking finding: reads the fix brief, fixes the code, asks before it commits and pushes, then asks Stableship to verify the fix. |
| `/stableship:gate why <findingId or runId>` | Why it blocks: the rule, the proof, and how often it was seen. |
| `/stableship:gate skip "<reason>"` | Records that the pushed commit needs no check. A change to sign-in, data or payments gets its minimum check anyway. |
| `/stableship:gate test <feature>` | Writes tests in your repository's own framework from the rules and the findings fixed so far, and runs them. |

Stableship checks the code on GitHub, not your local files. `check` tells you when you have unpushed work, and `fix` pushes the fix (after asking) before it can verify it. `fix` never weakens tests, row level security policies or auth checks to make a finding go away.

## Keep Claude out of .env files

A plugin cannot set permission rules, so add these to your project's `.claude/settings.json` (or `~/.claude/settings.json` for every project):

```json
{
  "permissions": {
    "deny": ["Read(.env)", "Read(.env.*)", "Edit(.env)", "Edit(.env.*)"]
  }
}
```

These rules cover Claude's file tools at any depth in the project. They do not stop a shell command such as `cat .env`, so keep Bash prompts on.

## If something is off

- **`/stableship:gate` is missing.** Run `/plugin` and check that `stableship` is installed and turned on.
- **Tools fail with "unauthorized".** Run `/mcp`, pick the Stableship server and choose **Authenticate**. If you disconnected it in Stableship (**Settings**, then **Connections**, then **Connected apps**), authenticate again.
- **"Not connected" for your repository.** The repository's GitHub `origin` must be a repository connected to a Stableship app. Check with `git remote get-url origin`.
- **The check says your changes are not included.** Push the branch, then check again.
- **No note at the start of a session.** That is expected when nothing blocks.