> ## Documentation Index
> Fetch the complete documentation index at: https://jam.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started

> Give your coding agent a Jam to read and a way to prove the fix. Install the Jam CLI, add the agent skills, and paste a Jam link.

Someone on your team hits a bug, records a Jam, and drops the link in your issue tracker. Later that day a pull request is open. It carries a video of the fix working. Nobody typed a repro, nobody scrubbed a video, nobody pasted a stack trace into a chat window. Your coding agent started from the link.

That is what the Jam CLI is for. A coding agent lives in a terminal, and the CLI puts a Jam there: the console errors, the failed requests, the clicks, and the frames of what was on screen. Then it records the fix and hands back a link.

Every read and write in Jam is a command, output is JSON when piped, and it runs on macOS, Linux, and Windows. The full command list is in the [CLI reference](/docs/cli-reference).

## Quickstart

<Steps>
  <Step title="Install the CLI">
    ```bash theme={"theme":"css-variables"}
    curl -fsSL https://native.jam.dev/install | bash
    ```

    On Windows, run `powershell -c "irm https://native.jam.dev/install.ps1 | iex"`. See [Install](/docs/cli-reference#install) for platform notes.
  </Step>

  <Step title="Log in">
    ```bash theme={"theme":"css-variables"}
    jam auth login
    ```

    This opens a browser. For CI or WSL, pipe a [personal access token](/docs/personal-access-tokens) into `jam auth login --token` instead.
  </Step>

  <Step title="Read a Jam">
    ```bash theme={"theme":"css-variables"}
    jam list jams --limit 5
    jam get network <id> --status 5xx
    ```

    You are in. Everything the Jam captured is one command away.
  </Step>

  <Step title="Teach your agent">
    ```bash theme={"theme":"css-variables"}
    jam skills install
    ```

    This writes two skill files where your agent reads them (Claude Code, Cursor, Codex, OpenCode). A skill is a short Markdown guide the agent loads when the work matches. `jam-cli` teaches it to read a Jam. `jam-proof` teaches it to record one.
  </Step>

  <Step title="Paste a Jam link">
    Give your agent a Jam link and a sentence: "Fix this and show me it works." The agent does the rest.
  </Step>
</Steps>

## What to say to your agent

Once the skills are installed you talk in English, not in flags. The agent picks the commands. These are the sentences that do the most work.

| Say this                                                                 | What the agent does                                                                              |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `Fix this: <jam link>`                                                   | Reads the console errors, failed requests, and frames from the Jam, then patches the code.       |
| `Fix this and show me it works: <jam link>`                              | The same, then records the fix running and hands back a second Jam link.                         |
| `Record this test run and put the link on the PR`                        | Wraps the test in `jam record run`, so a failure still fails the build and still leaves a Jam.   |
| `Record yourself reproducing this in the browser, then send me the link` | Drives a browser through the recorder, so the Jam carries the console, network, and every click. |
| `Show me the bug, then show me the fix`                                  | Two Jams, before and after. Use it when the change is visual.                                    |

The words that matter are the ones that ask for evidence: `show me`, `prove`, `record`, `send me the link`. They are what tells the agent to reach for `jam record` instead of stopping at a green test.

## An agent fixes the bug from the link

Say a teammate records the checkout page failing and sends you `https://jam.dev/c/abc123`. You paste it to your agent with one line: "Fix this." Here is what happens with the skills installed.

**It reads the evidence, not the ticket.** The agent pulls the Jam and filters to what matters.

```bash theme={"theme":"css-variables"}
jam get jam abc123
jam get network abc123 --status 5xx
jam get console abc123 --level error
```

The network read returns one request: `POST /api/checkout` answered 500 at 42 seconds, response body included. The console read returns the `TypeError` the page threw a moment later, with the stack trace. The agent now has the failing endpoint, the payload that was sent, and the line in the frontend that could not handle the answer.

**It looks at the screen when it needs to.** Logs say what broke. Frames say what the person saw.

```bash theme={"theme":"css-variables"}
jam get frames abc123 --at 42000
```

A jpg of the checkout form at the moment of failure: card field filled, button greyed out. The agent can tell the request fired on submit and the UI never recovered.

**It fixes the code.** With the endpoint, the payload, and the stack trace, the agent greps the handler, finds the field the API stopped returning, and patches both sides. That is the same work a person would do, minus the hour spent reproducing. The agent started from what happened instead of from a guess.

**It closes the loop on the Jam.** The agent comments what it found, pinned to the failure.

```bash theme={"theme":"css-variables"}
jam create comment abc123 "500 on /api/checkout: totals missing when a coupon is applied. Fix in #1423." --at 42000
```

The reporter sees the comment on the share page. Nobody wrote a repro, nobody scrubbed a video.

## An agent proves the fix

Add three words to the prompt: "and show me." The `jam-proof` skill picks up from the fix.

```bash theme={"theme":"css-variables"}
jam record run --pid $BROWSER_PID --url https://example.com/checkout --title "Checkout completes after fix" -- bun run e2e/checkout.ts
```

The agent launches a dedicated browser window and keeps its process ID. The CLI records that window while the check drives it, uploads, and prints the receipt:

```json theme={"theme":"css-variables"}
{ "id": "def456", "url": "https://jam.dev/c/def456", "durationMs": 20480 }
```

The agent puts that link in the pull request and on the original Jam. You open the PR, watch 20 seconds of checkout completing, and merge. For a bug fix, ask for two Jams: one of the bug, one of the fix.

<Tip>
  Agents guess at flags without the skills. With them, the agent reads console errors first, opens frames when logs run out, and pages with `--after`. Run `jam skills install --project` to install into the repo instead of your home directory, or `jam skills path` to preview the destination.
</Tip>

## What you can do with it

### Prove a change works

`jam record run` records the screen while a command runs, then uploads and prints a link. Wrap a test, a script, or the steps an agent drives. The wrapped command keeps its own exit code, so a failing test still fails the pipeline and still leaves a Jam behind.

```bash theme={"theme":"css-variables"}
jam record run --app "Google Chrome" --title "Checkout completes" -- bun run e2e/checkout.ts
```

When there is no command to wrap, `jam record start` and `jam record stop` bracket steps the caller runs itself. Run `jam record status` between calls to check the recording without stopping it. `jam record` runs on macOS and Linux. Run `jam doctor` to check recording readiness. See [Record a window or the desktop](/docs/cli-reference#record-a-window-or-the-desktop).

When the thing being recorded is a browser an agent drives, add `--cdp` and the Console, Network, and user-action panels fill from the browser itself. See [Record an agent's browser](/docs/cli-record-browser).

### Turn a Playwright failure into a watchable Jam

Configure Playwright to keep a video and a trace for failed tests, then point the CLI at both. The Jam plays the video with the run's console logs and network requests lined up on the timeline, and shows what the test typed with sensitive fields masked.

```bash theme={"theme":"css-variables"}
jam create jam '{
  "kind": "video",
  "url": "https://example.com/checkout",
  "videoPath": "./test-results/checkout/video.webm",
  "playwrightTracePath": "./test-results/checkout/trace.zip",
  "screenDimensions": { "width": 1280, "height": 720 }
}'
```

In `playwright.config.ts`:

```ts theme={"theme":"css-variables"}
use: { video: "retain-on-failure", trace: "retain-on-failure" }
```

In a GitHub Actions job, one step after the test step builds the payload from the artifacts Playwright left and uploads it:

```yaml theme={"theme":"css-variables"}
- name: Upload failure as a Jam
  if: failure()
  env:
    JAM_TOKEN: ${{ secrets.JAM_TOKEN }}
  run: |
    curl -fsSL https://native.jam.dev/install | bash
    dir=$(ls -d test-results/*/ | head -1)
    cat > jam.json <<EOF
    {
      "kind": "video",
      "url": "https://example.com/checkout",
      "videoPath": "${dir}video.webm",
      "playwrightTracePath": "${dir}trace.zip",
      "screenDimensions": { "width": 1280, "height": 720 }
    }
    EOF
    ~/.local/bin/jam --json create jam @jam.json
```

Playwright writes each failed test's artifacts into its own folder under `test-results/`. The example takes the first one. Loop over the folders to upload every failure.

`JAM_TOKEN` holds a [personal access token](/docs/personal-access-tokens). The CLI never writes it to disk. Post the printed URL on the job and reviewers watch the failure instead of reading a stack trace. See [Create and update Jams](/docs/cli-reference#create-and-update-jams).

## Why the CLI over MCP

Jam also has a [Model Context Protocol (MCP) server](/docs/jam-mcp). Both read the same Jam. Pick MCP when your agent only needs the bug context and you want zero install. Pick the CLI when you want any of these.

* **It records.** `jam record run` captures a window while a check runs and uploads a Jam. MCP reads Jams. It cannot make one. Proof of work only exists on the CLI side.
* **It runs anywhere a shell runs.** CI jobs, cron, a Docker container, a script on a teammate's machine. No MCP client, no per-tool config, one `JAM_TOKEN`.
* **It works with every agent.** Any agent that can run a command can use it, including ones with no MCP support. `jam skills install` targets Claude Code, Cursor, Codex, and OpenCode, one runtime per run (`--target <agent>`), and `jam agent-context` covers any agent they do not.
* **It ships the workflow, not only the tools.** `jam skills install` teaches the agent the order of operations: errors first, frames when logs run out, record the fix, comment the link. An MCP tool list leaves that up to the model.
* **It creates Jams from test runs.** Point `jam create jam` at a Playwright video and trace and the failure becomes a watchable Jam with logs on the timeline.
* **It composes.** Pipe to `jq`, branch on exit codes, page with `--after`, write frames to disk and open them in whatever you like.
* **It keeps context small.** Filters like `--level error` and `--status 5xx` return only the events that matter, and output lands on disk or in a pipe until the agent asks for it.
* **It is yours to wrap.** `jam agent-context` prints the full command surface as JSON (argument types, flag enums, output shapes), kept in step with the commands by a test. Skip the skills and build your own tool definitions on it: `jam agent-context | jq '.commands["get.jam"]'`.

| You need the agent to                                           | Use |
| --------------------------------------------------------------- | --- |
| Read a Jam from an editor or chat client with nothing installed | MCP |
| Record proof of a fix                                           | CLI |
| Run in CI or a shell script                                     | CLI |
| Turn a Playwright failure into a Jam                            | CLI |
| Work in an agent that has no MCP support                        | CLI |

## Next

* [Record an agent's browser](/docs/cli-record-browser) captures the console, network, and clicks from any browser an agent drives over the DevTools protocol.
* [CLI reference](/docs/cli-reference) lists every command, flag, exit code, and environment variable.
* [Personal access tokens](/docs/personal-access-tokens) covers scopes, expiration, and rotation for CI.
* [MCP](/docs/jam-mcp) sets up the same bug context in Claude, Cursor, VS Code, and ChatGPT.