Install in Claude Code

SayWhat works like an editor who checks a work order before the crew begins. It turns your rough request into a clear plan. Claude Code then writes the code.

This guide uses the manual install for the Claude Code beta adapter. The terminal commands below are for macOS or Linux. You can ask Claude Code to help you follow them.

1. Check what you need

Install Claude Code and sign in. Check it in your terminal:
```
claude --version
```
If the command is missing, follow Claude Code’s install guide. A ~/.claude folder alone does not prove the terminal app is installed.
Have Node.js and a local copy of the SayWhat source files. Node.js runs the small program that connects Claude Code to SayWhat.
For a licensed install, get your activation code from Account → Setup. Exchange it through POST https://saywhat.foo/api/activate using adapter claude-code. Save the returned licenseToken privately; it is shown only once. You can ask Claude Code to handle this without printing the token.

2. Connect the SayWhat tool

MCP is a standard way for AI agents to use tools. Think of it as a cable that connects Claude Code to SayWhat. Run this from your copy of the SayWhat source files. Replace the folder path first:

cd <path-to-saywhat-repo>
claude mcp add --scope user \
  --env SAYWHAT_API_URL=https://saywhat.foo \
  --env SAYWHAT_DEFAULT_AGENT=claude-code \
  --transport stdio \
  saywhat -- node "$(pwd)/apps/claude-code-plugin/mcp/server.mjs"

Keep --transport stdio just before saywhat, as shown. This avoids the “Invalid environment variable format” error that some versions produce.

For a licensed install, store SAYWHAT_LICENSE_TOKEN in the SayWhat server’s private environment settings. The token is like a key. Keep it out of chat, shell history, and shared files. See Claude Code’s MCP guide for tool settings.

3. Add the skill

A skill is a short instruction sheet. This one tells Claude Code when to call SayWhat. From the same source folder, run:

mkdir -p ~/.claude/skills
ln -s "$(pwd)/apps/claude-code-plugin/skills/saywhat" ~/.claude/skills/saywhat

This creates a link to the skill, much like a shortcut to a file. Keep your source folder in place. If the link already exists, check where it points before replacing it.

4. Add the Preflight rule

Open apps/claude-code-plugin/CLAUDE.md. Copy its SayWhat instructions into ~/.claude/CLAUDE.md. Create the personal file if it does not exist. Keep any other rules you already have, and add the SayWhat section only once.

Think of this file as a standing work rule: check the plan before starting the job. It tells Claude Code to run Preflight at the start of a coding request.

5. Check the connection

Run this in your terminal:
```
claude mcp list
```
Look for saywhat with a connected status.
Exit Claude Code and start a fresh session so it reads the new settings.
Ask: Run SayWhat Preflight for “add a hello comment” with targetAgent claude-code. Show the receipt, but do not edit files.
Look for the SayWhat.foo PreFlight receipt. On a normal coding request, Claude Code should run this check before editing.

Common problems

claude: command not found: install the terminal app using the guide in step 1, then open a new terminal.
Invalid environment variable format: keep --transport stdio between the last --env option and the name saywhat.
SayWhat will not connect: check Node.js and the server file path. Run claude mcp list again after fixing them.
Preflight is skipped everywhere: check the skill link and the SayWhat rule in ~/.claude/CLAUDE.md. Start a new session.
Only one project skips Preflight: check its own instructions for a conflict. Add a clear rule to that project’s CLAUDE.md: Run SayWhat Preflight first. Call saywhat_preflight with targetAgent claude-code before editing.
Need a fallback: use the web compiler, then paste the plan into Claude Code.

Optional: edit the connection settings yourself

You can add the same server to your personal ~/.claude.json settings instead of using the command in step 2. Merge it with your current settings. Replace the path with the full path to the server file:

{
  "mcpServers": {
    "saywhat": {
      "type": "stdio",
      "command": "node",
      "args": ["<path-to-repo>/apps/claude-code-plugin/mcp/server.mjs"],
      "env": {
        "SAYWHAT_API_URL": "https://saywhat.foo",
        "SAYWHAT_DEFAULT_AGENT": "claude-code"
      }
    }
  }
}

A project can also use .mcp.json. If that file is shared through Git, keep license tokens out of it. You still need the skill and Preflight rule from steps 3 and 4.

Still stuck? Contact us with the step that failed and its error message. Leave out activation codes and license tokens.