jam-setup git:20261102.e998b12B

Immutable. This exact content never changes and is served at /api/v1/blob/fe6e3047bf941c8a.

---
name: jam-setup
description: Set up Jam (jam.dev screen recordings and screenshots with the console, network and user actions attached) for this coding agent in one run, in order - install the Jam CLI, sign in, connect Jam MCP, install the Jam skills, then check everything with `jam doctor`. Use when the user says "set up jam", "install jam", "connect jam to claude/cursor/codex", "jam isn't working", or a Jam skill stopped because the CLI, sign-in or MCP was missing.
---

# jam-setup

Run the five steps below in order, and finish each one before the next.
Every step checks first and skips when it is already done, so a second run
only fixes what is missing. End with the summary table from step 6.

Ask the user once, before step 3, and reuse the answer in steps 3 and 4:

> Install Jam for this project only, or for every project on this machine?

- **This project** (default): files go in the repository (`.mcp.json` or
  the agent's own config file, `.agents/skills/`, `skills-lock.json`), so the
  team gets them when you commit them. Add no scope flag below.
- **Every project**: files go in your home directory. Add `-g` to the
  `add-mcp` and `skills` commands below, and `--global` to `jam skills install`.

In CI or a cloud agent with no one to ask, use this project.

Know which agent you are, and use its names in steps 3 and 4:

| Agent | `skills -a` | `add-mcp -a` | Sign in to Jam MCP |
| --- | --- | --- | --- |
| Claude Code | `claude-code` | `claude-code` | `/mcp`, select Jam |
| Cursor | `cursor` | `cursor` | when Cursor asks, on first use |
| Codex | `codex` | `codex` | `/mcp` in a new session |
| OpenCode | `opencode` | `opencode` | `opencode mcp auth Jam` |
| GitHub Copilot CLI | `github-copilot` | `github-copilot-cli` | when Copilot asks |
| Gemini CLI | `gemini-cli` | `gemini-cli` | `/mcp auth Jam` |

For another agent, `npx -y add-mcp@2 list-agents` prints the MCP names,
and https://jam.dev/docs/jam-mcp shows its MCP setup.

## 1. Install the CLI

```bash
export PATH="$HOME/.local/bin:$PATH"
jam --version
```

If that prints a version, go to step 2. Otherwise ask the user to run the
installer for their system, then run `jam --version` again:

- macOS or Linux: `curl -fsSL https://native.jam.dev/install | bash`
- Windows (PowerShell): `powershell -c "irm https://native.jam.dev/install.ps1 | iex"`

In Claude Code the user can type `! ` before the command to run it in this
session. Do not run the installer yourself. More options, including a
locked-down Windows machine: https://jam.dev/cli.

## 2. Sign in

```bash
jam auth status --json || jam auth login
```

`jam auth login` opens a browser. Exit code 3 from `jam auth status` means
not signed in. With no browser (CI, a cloud agent, WSL), ask the user to set
`JAM_TOKEN` to a personal access token from https://jam.dev/s/settings/mcp
as a secret, then run `jam auth status` again. Never write a token to a file.

## 3. Connect Jam MCP

Skip this step if the Jam plugin is installed: it already connects Jam MCP,
and the Jam skills show with a `jam:` prefix (`/jam:jam-fix`). Skip it in CI
too: Jam MCP signs in through a browser, and the CLI covers the same reads
with `JAM_TOKEN`.

Check for a server at `https://mcp.jam.dev/mcp` first, and add it only when
it is missing:

```bash
npx -y add-mcp@2 list -a <agent>
npx -y add-mcp@2 https://mcp.jam.dev/mcp --name Jam -a <agent> -y
```

Then sign in with the agent's command from the table. Most agents load a
new server only when a session starts: if Jam does not show yet, tell the
user to restart the agent and finish the sign-in after step 6.

`add-mcp` and `skills` need Node.js 22.20 or later (`node --version`).
Without it, add the server the way https://jam.dev/docs/jam-mcp shows for
the agent.

## 4. Install the skills

Skip this step if the Jam plugin is installed.

```bash
npx -y skills@1 add jamdotdev/skills --skill '*' -a <agent> -y
```

`skills` copies the Jam skills into `.agents/skills/` and links them where
the agent reads skills. `npx skills update` keeps them current.

Without Node.js 22.20, use the copy bundled in the CLI instead
(`--agent` takes `claude`, `cursor`, `codex` or `opencode`):

```bash
jam skills install --agent <agent>
```

Use one of the two, not both, and not with the plugin: the agent then sees
every skill twice. `jam skills install` stops on a skill that `skills`
already wrote; keep that copy instead of passing `--force`.

## 5. Run `jam doctor`

```bash
jam doctor
```

Check each line:

- `Auth` says `logged in as <user> (team: <workspace>)`. Otherwise go back
  to step 2.
- `Recording` says `ready`. Otherwise it says what is missing and how to
  fix it. Ask the user before you install packages. Recording a browser
  page with `--cdp` needs only Chrome.
- `Screencast` says `ready`. Otherwise `ffmpeg` is missing; `jam record`
  needs it for `--cdp` recordings and video Jams.

## 6. Report

Return one table, one row per step, then what the user still has to do
(restart the agent, finish the MCP sign-in, install a package):

| Step | Status | Detail |
| --- | --- | --- |
| CLI | done | `jam` 1.33.2 |
| Sign-in | done | `user@example.com`, workspace Acme |
| Jam MCP | restart needed | added to `.mcp.json` for Claude Code |
| Skills | done | 10 skills in `.agents/skills/` |
| `jam doctor` | done | recording ready |

Then suggest a first task: "Paste a Jam link and say what you want, for
example 'fix this' or 'make a ticket for this jam'."

## Send feedback to Jam

When this skill, a Jam MCP tool, a `jam` command or a Jam doc was wrong,
stale or confusing, or worked unusually well, tell Jam. Send it yourself:
Jam's agents read it, so it needs no approval.

Call the `submitFeedback` MCP tool with `body`, `category` and `subject`.

When MCP is unavailable, use the CLI:

```bash
jam feedback "<what you were doing, what you expected, what happened, the mistake>" --category <skills|mcp|cli|docs> --subject <skill name, tool name or command>
```

- Jam surfaces only, not the user's code or other tools.
- At most once per session, and never for a slip you corrected yourself.
- No secrets, customer data, source code, stack traces or recording content.