# Install GooseWorks

You are an AI agent reading this because a user asked you to install GooseWorks.

GooseWorks gives coding agents marketing and growth skills (research, ads, video, product photos, social and web data) plus the GooseWorks MCP server, which connects the agent to the user's GooseWorks account. Installing is free. Some skills spend GooseWorks credits when they run; the skills say so before they spend.

Follow the steps in order. Only ever run `npx gooseworks@latest …` commands. Do not edit config files by hand and do not run anything else.

## If you are a chat app or cannot run terminal commands

If you are Claude Code on the web (claude.ai/code) or ChatGPT agent, skip this section and follow the next one. If you are Claude Code and your shell runs on the user's own computer (in the Claude desktop app or a terminal on that computer), skip this section and the next one, and follow steps 1 to 4. If you are Claude Code and your shell runs somewhere else (over SSH, on a remote dev machine, or in a hosted environment), skip this section and follow the next one, even if you were started from the Claude desktop app.

If you are claude.ai, the Claude desktop app's chat, ChatGPT, or another app without a terminal, do not try to install. On claude.ai and in the Claude desktop app's chat this holds even when you can run code, because that code runs in a throwaway sandbox, not on the user's computer. Tell the user this, word for word, then stop:

> Add `https://mcp.gooseworks.ai/mcp` as a custom connector (MCP server) in your app's settings, sign in with Google when it asks, then come back here and ask me for a GooseWorks task.

Video ads work in chat apps too, through the connector. When a video is ready to be made, GooseWorks gives the user one command to run on their own computer.

## If your shell runs in the cloud

Your shell runs in the cloud when it is not on the user's own computer: ChatGPT agent, Meta AI, Grok, Codex cloud, Claude Code on the web (claude.ai/code), a remote machine reached over SSH, a remote dev machine, or any other hosted sandbox. A browser sign-in cannot reach you there, so sign in with a code instead, and skip steps 1 to 3 below.

1. Ask the user before you install. Tell them it saves a GooseWorks sign-in file in `~/.gooseworks/` and skill files in `~/.agents/skills/` in this sandbox, and changes nothing else. Wait for a clear yes.
2. Run this. It prints a link and a code, then exits. If it says it is already logged in, skip step 3 and go straight to step 4:

```bash
npx gooseworks@latest login --device --no-wait
```

3. Show the user the link and the code exactly as printed. Ask them to open the link on any device, sign in, check the code matches and tap Approve, then tell you.
4. When the user says they approved (or straight away if step 2 said you are already logged in), run this. It finishes the sign-in if needed and installs the GooseWorks skills:

```bash
npx gooseworks@latest install --skills-only
```

   It waits for the approval. If your shell stops it before the user has approved, run the same command again; it picks up the same sign-in. If it prints a new link instead (the old code expired or was canceled), show the user that link and code, and run this command again once they have approved.

   If the user asked for a specific skill ("including the goose-graphics skill"), add `--with <skill-slug>` to this command once per skill, for example `--with goose-graphics`, and keep it every time you run the command again.
5. Check the connection by running `npx gooseworks@latest tool account_whoami`. It prints the signed-in account. If it fails, show the user the error and stop.
6. In this sandbox you call GooseWorks tools through the CLI. Wherever these steps or the GooseWorks skills name a tool (for example `brand_setup`), run `npx gooseworks@latest tool <name> '<arguments as a JSON object>'`. Run `npx gooseworks@latest tool --list` once to see every tool and the rules for using them. Before calling a tool whose inputs you have not seen, run `npx gooseworks@latest tool <name> --schema` to read its description and input schema; `--list` only gives names and summaries. Read `~/.agents/skills/gooseworks/SKILL.md` for how to work with GooseWorks.
7. Tell the user GooseWorks is connected, then continue with step 4 below (set up the user's brand), calling the tools through the CLI.

Never ask the user to paste a sign-in key or a localhost address into the chat.

## 1. Ask the user before you install

Tell the user exactly what will happen, then wait for a clear yes. Do not run anything until they confirm.

- You will run one command: `npx gooseworks@latest install --all --mcp`. `--all` sets up every coding agent it finds on this computer (Claude Code, Codex, Cursor), so the user gets GooseWorks in all of them at once.
- It writes GooseWorks skill files to `~/.agents/skills/` and links them into each detected agent's skills folder (`~/.claude/skills/` for Claude Code, `~/.codex/skills/` for Codex; Cursor reads `~/.agents/skills/` directly).
- It opens a browser for Google sign-in and saves the sign-in token to `~/.gooseworks/credentials.json` (file mode 0600).
- It registers the `gooseworks` MCP server in the config of each agent it detects. Each entry contains the same sign-in token, so the agent can call GooseWorks. The file depends on the agent:
  - Claude Code: `~/.claude.json`
  - Codex: `~/.codex/config.toml`
  - Cursor: the global Cursor MCP config (macOS `~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/config.json`, Linux `~/.config/Cursor/User/globalStorage/cursor.mcp/config.json`, Windows `%APPDATA%\Cursor\User\globalStorage\cursor.mcp\config.json`). If the current folder or any folder above it has a `.cursor/` directory, it also writes that project's `.cursor/mcp.json`. Tell the user that path and that it will contain the token, so they can keep it out of version control.
- It writes no other files. Installing is free.

## 2. Run the install

```bash
npx gooseworks@latest install --all --mcp
```

Run it exactly as written. Always use `--all`; do not replace it with `--claude`, `--codex` or `--cursor`. Always keep `--mcp`. Never pass `--no-mcp`.

If the user asked for a specific skill ("including the goose-graphics skill"), add `--with <skill-slug>` once per skill, for example `--with goose-graphics`.

The command opens a browser for Google sign-in and always prints the sign-in URL. If no browser opens, show the user that URL and wait until they have signed in. Never paste or store the token yourself.

## 3. Check that it worked

```bash
npx gooseworks@latest doctor --json
```

It prints JSON: `{ "ok": boolean, "checks": [{ "id", "label", "ok", "fix", "detail" }] }`. The command exits non-zero when any check fails; that alone does not mean the install failed. Read the checks by `id`:

| Check id | Means | If `ok` is false |
|---|---|---|
| `login` | Signed in | Install failed. Show the user the `fix` text, and stop. |
| `mcp` | MCP server URL saved | Install failed. Show the user the `fix` text, and stop. |
| `node`, `ffmpeg`, `ffprobe`, `chromium` | Local video rendering prerequisites | Not an install failure. Carry on and say nothing to the user about them now. They only matter for making videos on this computer, and GooseWorks tells the user in plain words if a video ever needs something. |

So: if `login` and `mcp` both pass, the install worked, even when `ok` is false because of the video checks. Do not try to install ffmpeg or a browser yourself.

Carry on in this session. The GooseWorks MCP tools load by themselves the next time this agent starts, so the user does not need to quit or reopen anything. Until then, call GooseWorks tools through the CLI:

- Check the connection with `npx gooseworks@latest tool account_whoami`. It prints the signed-in account. If it fails, show the user the error and stop.
- Run `npx gooseworks@latest tool --list` once to see every tool and the rules for using them.
- Before calling a tool whose inputs you have not seen, run `npx gooseworks@latest tool <name> --schema` to read its description and input schema; `--list` only gives names and summaries.
- Call any tool with `npx gooseworks@latest tool <name> '<arguments as a JSON object>'`. Wherever these steps or the GooseWorks skills name a tool (for example `brand_setup`), call it this way.
- Read `~/.agents/skills/gooseworks/SKILL.md` for how to work with GooseWorks.

If the GooseWorks MCP tools are already available to you in this session, you can call them directly instead. If you are not Claude Code, Codex or Cursor (for example Hermes or another agent), this install cannot register GooseWorks tools for you, so keep using the CLI in every session.

Tell the user GooseWorks is installed, then go straight to step 4 in this session.

## 4. Set up the user's brand

Unless the user said they already set up their company or asked to skip onboarding: call `brand_setup` with `{"action":"status"}` and follow only the `next_step` in its answer. Each answer says what to ask the user and which call to make next; do not ask for anything it does not ask for. Keep the user's original request, and carry it on as soon as an answer says setup is done.

If the user said to skip onboarding, report the account that `account_whoami` returned and finish.