# Quickstart

Run the included Notes demo. The demo is a small notes app with the ShappyChat in it. The chat lists and creates notes through the MCP tools of the app.

## Requirements

- Node.js 22.19 or newer
- npm
- The ShappyChat source checkout

## Run the scripted demo

The scripted demo needs no model and no API key.

```bash
npm ci
npm run example
```

The launcher builds the SDK and the demo. Then it opens a private pairing link in your browser.

1. In the Notes header, click **Chat**.
2. Click **List my notes**. The chat calls the `list_notes` tool of the app.
3. Click **Create a demo note**. The chat calls `add_note`. The new note shows in the app.

> **Note:** The scripted demo does not use an AI model. It is labelled **Scripted demo (no LLM)**. It gives fixed answers for the two example prompts. The tool calls, the MCP transport, the chat UI and the storage are real product code.

## Use a real model

You can use any server that supplies an OpenAI-compatible API, for example LM Studio. Load a chat model that supports tool calls.

```bash
SHAPPYCHAT_MODEL_URL=http://127.0.0.1:1234/v1 npm run example
```

If your model server needs a key, set `SHAPPYCHAT_MODEL_API_KEY` in your environment. Do not put the key in source files.

## Addresses and files

| Item | Value |
| --- | --- |
| Notes app | `http://127.0.0.1:8850` |
| Demo runtime | Port 8851 |
| Scripted model | Port 8852 |
| Private pairing link | `~/.shappychat/example-notes/launch-url` |

All services listen only on the local computer (loopback).

To start without a browser window, use this command. Then open the private pairing link from the file.

```bash
npm run example -- --no-open
```

> **Warning:** The pairing link contains a key. Do not share or publish it.

## Try the chat layouts

Click **Chat** in the Notes header. Select a layout:

- **Right panel** (recommended): the chat slides in from the right side.
- **Bottom-right dot**: a small button opens a floating chat window.
- **Bottom-centre island**: a message bar at the bottom. The conversation shows above it.
- **Side by side**: the app and the chat share the window.

The conversation and your unsent text stay when you change the layout.