---
url: https://chartbuddy.io/hub/docs/getting-started.md
---
# Getting Started

Documentation for **Chartbuddy Hub** – the free desktop app for consultants, analysts, and founders who chart with AI.

Hub is the Chartbuddy desktop application. It wraps the full business chart library and makes charts editable on your machine.

## How Hub fits Chartbuddy

| Surface | Role |
|---------|------|
| **Hub** | Desktop editor – prompt from AI, refine locally, push & pull |
| **Embed** | JavaScript package for dashboards, products, and AI chats |
| **Google Slides** | Native editor inside decks, synced to Sheets |
| **PowerPoint** | Coming soon |

Embedding Chartbuddy as HTML? See the [Embed docs](https://chartbuddy.io/embed/docs/getting-started.md) / [`llms.txt`](https://chartbuddy.io/embed/docs/llms.txt) instead.

## Paths

* [Install Hub on Windows](https://chartbuddy.io/hub/docs/getting-started/windows.md) – download, click past SmartScreen, finish setup, and sign in
* [A note on Microsoft Defender](https://chartbuddy.io/hub/docs/getting-started/windows-defender.md) – why “Windows protected your PC” appears and how to continue
* [Install Hub on macOS](https://chartbuddy.io/hub/docs/getting-started/macos.md) – download the `.dmg`, Applications, Gatekeeper
* [Connect MCP](https://chartbuddy.io/hub/docs/connect-mcp.md) – overview, then [Cursor](https://chartbuddy.io/hub/docs/connect-mcp/cursor.md) / [Claude Code](https://chartbuddy.io/hub/docs/connect-mcp/claude-code.md) / [OpenCode](https://chartbuddy.io/hub/docs/connect-mcp/opencode.md) / [Google Antigravity](https://chartbuddy.io/hub/docs/connect-mcp/antigravity.md) / [ChatGPT / Codex](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt-codex.md) / [ChatGPT (web)](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt.md) / [Claude (web)](https://chartbuddy.io/hub/docs/connect-mcp/claude.md)
* Agent index: [`/hub/llms.txt`](https://chartbuddy.io/hub/llms.txt) → [`mcp-setup.md`](https://chartbuddy.io/hub/mcp-setup.md) → docs `.md` pages
* [Desktop basics](https://chartbuddy.io/hub/docs/guides/desktop-basics.md) – first launch and everyday workflow
* [Push & pull](https://chartbuddy.io/hub/docs/guides/push-and-pull.md) – move charts between Hub and other surfaces

## Also browse

* [Help Center](https://chartbuddy.io/help) – end-user guides for Google Slides
* [Download Hub](https://chartbuddy.io/getstarted#hub) – get the desktop app

---

---
url: https://chartbuddy.io/hub/docs/getting-started/windows.md
---
# Install Hub on Windows

Download starts from the [Windows download page](https://chartbuddy.io/download/hub/windows). The installer is `Chartbuddy_windows_x64-setup.exe`.

If Windows shows **Windows protected your PC**, that is SmartScreen. [Why it appears and how to continue](https://chartbuddy.io/hub/docs/getting-started/windows-defender.md).

## 1. Open the installer

When the download is complete, open **Chartbuddy\_windows\_x64-setup.exe** from your browser download bar or Downloads folder.

![Chrome download bar showing the Chartbuddy Windows installer](https://chartbuddy.io/images/hub-install/download-installer.png)

## 2. Select “More info”

Windows may show this message while it builds familiarity with a new download. Select **More info** to see the installer and publisher details.

![Windows protected your PC message with the More info link](https://chartbuddy.io/images/hub-install/defender-more-info-annotated.png)

## 3. Select “Run anyway”

Select **Run anyway** to start the installer.

The publisher should be **Chartbuddy B.V.** If it is different, or Windows reports an invalid signature, do not continue.

![Windows protected your PC message showing Chartbuddy B.V. and Run anyway](https://chartbuddy.io/images/hub-install/defender-run-anyway-annotated.png)

## 4. Follow the installer

Click through the Chartbuddy setup wizard. Keep the default options and select **Install**, then **Finish** when it completes.

![Chartbuddy Setup wizard welcome screen](https://chartbuddy.io/images/hub-install/follow-installer.png)

## 5. Sign in

When Hub opens, sign in with your **existing Chartbuddy account**, the same email you already use on chartbuddy.io.

![Chartbuddy Hub sign-in options for Google, SSO, and email](https://chartbuddy.io/images/hub-install/sign-in.png)

## For client IT and security teams

* Official download page: `https://chartbuddy.io/download/hub/windows%60
* Installer path: `https://chartbuddy.io/downloads/hub/Chartbuddy_windows_x64-setup.exe%60
* Expected Windows publisher: **Chartbuddy B.V.**

You can also confirm the signature in File Explorer: right-click the `.exe` → **Properties** → **Digital Signatures**.

## Next steps

[Connect an AI client](https://chartbuddy.io/hub/docs/connect-mcp.md) or read [Desktop basics](https://chartbuddy.io/hub/docs/guides/desktop-basics.md).

---

---
url: https://chartbuddy.io/hub/docs/getting-started/windows-defender.md
---
# Microsoft Defender / SmartScreen

Microsoft Defender SmartScreen may show **Windows protected your PC** when you open the Chartbuddy Hub installer. That message is common for a newly published desktop app. It is not a virus finding.

![Windows protected your PC, select More info](https://chartbuddy.io/images/hub-install/defender-more-info.png)

## Why it appears

Chartbuddy became a Microsoft developer in mid 2026. SmartScreen treats new publishers with extra caution until an app builds reputation, so this prompt is Microsoft being careful, not a malware result.

The installer is signed by **Chartbuddy B.V.** As more people install Hub from that publisher, the message should become less prevalent.

## How to continue

1. In the blue **Windows protected your PC** window, select **More info**.
2. Check that the **Publisher** is **Chartbuddy B.V.**
3. Select **Run anyway**.
4. Finish the setup wizard, then sign in with your existing Chartbuddy account.

If the publisher is missing, different, or Windows says the signature is invalid, do not continue. Delete the file and [contact us](https://chartbuddy.io/support).

![Windows protected your PC, select More info](https://chartbuddy.io/images/hub-install/defender-more-info-annotated.png)

![Confirm Chartbuddy B.V., then Run anyway](https://chartbuddy.io/images/hub-install/defender-run-anyway-annotated.png)

## Further notes on Microsoft Defender

Microsoft's own documentation confirms this is a reputation check, not a malware detection.

On how downloaded files are evaluated, Microsoft states that SmartScreen determines whether a downloaded app is potentially malicious by "checking downloaded files against a list of files that are well known and downloaded frequently. If the file isn't on that list, Microsoft Defender SmartScreen shows a warning, advising caution." ([Microsoft Defender SmartScreen overview](https://learn.microsoft.com/en-us/windows/security/operating-system-security/virus-and-threat-protection/microsoft-defender-smartscreen/))

On reputation specifically: "If a URL, a file, an app, or a certificate has an established reputation, users don't see any warnings. If there's no reputation, the item is marked as a higher risk and presents a warning to the user." ([Microsoft Defender SmartScreen overview](https://learn.microsoft.com/en-us/windows/security/operating-system-security/virus-and-threat-protection/microsoft-defender-smartscreen/))

Microsoft's developer guidance describes exactly this situation for a newly signed app: "Users may see a SmartScreen prompt indicating the app is unrecognized. For signed apps, the publisher name is displayed. Users should proceed only after verifying the source." It adds that "SmartScreen reputation builds up automatically. The prompt will stop appearing once the file hash has sufficient download history. There is no exact threshold, but it can take several weeks and hundreds of clean installs from a wide audience." ([SmartScreen reputation for Windows app developers](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/smartscreen-reputation))

## Next

Back to the [Windows install steps](https://chartbuddy.io/hub/docs/getting-started/windows.md).

---

---
url: https://chartbuddy.io/hub/docs/getting-started/macos.md
---

# Install Hub on macOS

Chartbuddy Hub is a free desktop application. This guide covers the macOS install end-to-end: download the `.dmg`, move Hub to Applications, and launch it once.

## 1. Download the installer

Direct download (Apple silicon / arm64 DMG):

**[Download Chartbuddy Hub for macOS](https://chartbuddy.io/downloads/hub/Chartbuddy_macos_aarch64.dmg)**

## 2. Open the disk image

1. In Finder, open the `.dmg` (usually in **Downloads**).
2. A window appears with the **Chartbuddy** app and an **Applications** shortcut.

## 3. Install into Applications

1. Drag **Chartbuddy** into the **Applications** folder.
2. Eject the disk image (sidebar or right-click → Eject).
3. You can delete the `.dmg` afterward.

Installing into `/Applications` is strongly recommended for MCP and AI clients – the launcher looks there first:

```bash
ls /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy
```

## 4. Launch Hub once

1. Open **Chartbuddy** from Applications (or Spotlight: `Chartbuddy`).
2. Approve any macOS prompts.
3. Leave Hub running while you use MCP tools, or let the MCP server start it on the first tool call.

You should see the Chartbuddy Hub window (desktop chart editor – no prompt box inside the app).

## Verify

| Check | Command / action |
|-------|------------------|
| App present | `ls /Applications/Chartbuddy.app` |
| Binary | `ls /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy` |
| Version | Open Hub → About (or check the window title / docs version) |
| MCP port | After Hub runs, `~/.chartbuddy/mcp-port` should exist |

## Troubleshooting

| Symptom | What to try |
|---------|-------------|
| DMG won't open | Re-download; confirm the file size isn't truncated |
| MCP tools missing | Hub in `/Applications`? Client restarted after MCP config? |
| Hub won't auto-launch | Start Chartbuddy once manually, then retry the MCP tool |

## Next steps

[Connect an AI client](https://chartbuddy.io/hub/docs/connect-mcp.md) or read [Desktop basics](https://chartbuddy.io/hub/docs/guides/desktop-basics.md).

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp.md
---

# Connect MCP

AI clients talk to **Chartbuddy Hub** through the **Model Context Protocol (MCP)**. Install Hub first: [Windows](https://chartbuddy.io/hub/docs/getting-started/windows.md) or [macOS](https://chartbuddy.io/hub/docs/getting-started/macos.md).

## How clients connect

Clients spawn the Chartbuddy **binary** with `--mcp` over **stdio**. That process talks to Chartbuddy Hub on loopback.

**Framing:** newline-delimited JSON-RPC (preferred) or Content-Length framed MCP. Responses match the request framing.

The MCP server ships inside the Chartbuddy binary. Nothing to `npm install` or launch with `npx`.

On macOS, auto-launch looks for Chartbuddy Hub in this order:

1. `/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy`
2. `~/.local/bin/chartbuddy` (optional symlink, **Help → Install CLI Symlink…**)
3. `chartbuddy` on your `PATH`
4. `open -a Chartbuddy` (Launch Services by name)

## Pick your client

| Client | Guide |
|--------|--------|
| **Cursor** | [Connect Cursor](https://chartbuddy.io/hub/docs/connect-mcp/cursor.md) |
| **Claude (web)** | [Connect Claude (web)](https://chartbuddy.io/hub/docs/connect-mcp/claude.md) |
| **Claude Code** | [Connect Claude Code](https://chartbuddy.io/hub/docs/connect-mcp/claude-code.md) |
| **OpenCode** | [Connect OpenCode](https://chartbuddy.io/hub/docs/connect-mcp/opencode.md) |
| **Google Antigravity** | [Connect Google Antigravity](https://chartbuddy.io/hub/docs/connect-mcp/antigravity.md) |
| **ChatGPT / Codex** | [Connect ChatGPT / Codex](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt-codex.md) |
| **ChatGPT (web)** | [Connect ChatGPT (web)](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt.md) |

## Shared config

Every client uses the same stdio spawn (`args`: `--mcp`):

::: code-group

```json [Windows]
{
  "mcpServers": {
    "Chartbuddy-Hub": {
      "type": "stdio",
      "command": "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Chartbuddy\\chartbuddy.exe",
      "args": ["--mcp"]
    }
  }
}
```

```json [macOS]
{
  "mcpServers": {
    "Chartbuddy-Hub": {
      "type": "stdio",
      "command": "/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy",
      "args": ["--mcp"]
    }
  }
}
```

:::

## Verify

### Status check (read-only)

Fast and synchronous. Never launches Chartbuddy Hub or opens UI:

::: code-group

```powershell [Windows]
& "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp-status
```

```bash [macOS]
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status
```

:::

`--mcp-doctor` is an alias. Exit `0` = Chartbuddy Hub bridge up; `1` = unreachable.

If the port file exists and Chartbuddy Hub windows are visible but status says unreachable, you may be in a **sandbox that denied loopback**. Approve access and re-run.

### Smoke test (optional)

Chartbuddy Hub must be running. Pipe newline JSON-RPC into `--mcp`:

::: code-group

```powershell [Windows]
@"
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_charts","arguments":{}}}
"@ | & "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp
```

```bash [macOS]
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_charts","arguments":{}}}' \
| /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp
```

:::

| Command | Behavior |
|---------|----------|
| `--mcp-status` / `--mcp-doctor` | Facts + exit; no launch. `--json` / `--setup` optional |
| `chartbuddy --mcp` | Long-lived MCP adapter (stdio); may auto-launch Chartbuddy Hub on first tool call |
| Open Chartbuddy.app | Starts the Chartbuddy Hub GUI |

## Using tools

* **`list_charts`** lists Hub windows (`chart-*`) and CE edit sessions (`ce:*`), each with `surface: tauri|ce`.
* Edits usually target a specific `chart_ref`.
* **`get_active_chart`** returns a real chart window (not menus/popovers).
* Edits happen in Chartbuddy Hub’s desktop windows. Hub has no in-app prompt box.

## Troubleshooting

| Symptom | Check |
|---------|-------|
| MCP tools missing in chat | Config saved? MCP refreshed / new chat? Server enabled for that conversation? |
| Chartbuddy Hub not starting | Launch Chartbuddy Hub; run `chartbuddy --mcp-status` |
| Status “unreachable” but Chartbuddy Hub windows open | Sandbox may have denied loopback. Approve network for `chartbuddy` |
| Permission / Gatekeeper | Open Chartbuddy Hub from its install location the first time |
| Wrong window targeted | Use `list_charts`; ignore popover/menu windows |
| Stale port file | Quit Chartbuddy Hub, delete the Hub `mcp-port` file if needed (macOS / Linux `~/.chartbuddy/mcp-port`, Windows `%USERPROFILE%\.chartbuddy\mcp-port`), relaunch |
| Project MCP config in git | Use user/global scope only |
| Client talking to the Hub `mcp-port` file as MCP | Client must spawn `chartbuddy --mcp` |
| Treating `--mcp-status` as a launcher | Read-only; open the app (or use `--mcp` tool calls) to start Hub |

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp/cursor.md
---

# Connect Cursor

Wire **Cursor** to Chartbuddy Hub over local stdio MCP.

## Setup via Chartbuddy Hub

1. Install Chartbuddy Hub and launch it once (approve OS security prompts).
2. Open **AI connections** in Hub (title-bar cable icon).

3) Connect **Cursor**. Hub writes the server into your user Cursor MCP config.

4. In Cursor, **Refresh MCP** (or restart Cursor) and enable Chartbuddy for the chat.

## Setup by prompting Cursor

Paste the following into a Cursor agent chat:

```text
Set up the Chartbuddy Hub MCP server for this Cursor install:

1. Detect my OS and find the Chartbuddy binary at its default install path:
   - macOS: /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy
   - Windows: %LOCALAPPDATA%\Programs\Chartbuddy\chartbuddy.exe
   If it's not there, ask me for the correct path. Don't guess or search the whole filesystem.

2. Open my user MCP config (create it if missing):
   - macOS / Linux: ~/.cursor/mcp.json
   - Windows: %USERPROFILE%\.cursor\mcp.json
   Prefer this user/global file – do not write a project-scoped mcp.json.

3. If mcpServers already has "Chartbuddy-Hub" or "chartbuddy" pointing at
   Chartbuddy with args ["--mcp"], tell me and stop.

4. Add or replace (leave other servers untouched):
   "Chartbuddy-Hub": {
     "type": "stdio",
     "command": "<resolved path>",
     "args": ["--mcp"]
   }
   Remove a legacy "chartbuddy" entry if it pointed at Chartbuddy.

5. Confirm the bridge: <resolved path> --mcp-status
   (exit 0 = up, exit 1 = unreachable. If unreachable, tell me to launch
   Chartbuddy Hub first. Don't launch it yourself.)

6. Tell me to Refresh MCP (or restart Cursor) and enable Chartbuddy for
   the chat. If tools still do not appear, start a new agent chat.
```

## Setup manually

### 1. Install Chartbuddy Hub

Install Chartbuddy Hub and launch it once before you add the server (approve OS security prompts).

### 2. Add a custom MCP in Cursor

In the **Agents** view:

1. Click **Customize** in the sidebar.
2. Select **MCPs**.
3. Click **New MCP Server**.
4. Choose **User** (not Workspace), so the server is available in every project, not just the current one.

That opens your user `mcp.json`:

* macOS / Linux: `~/.cursor/mcp.json`
* Windows: `%USERPROFILE%\.cursor\mcp.json`

Prefer this **Home / global** config – do not commit a project-scoped copy.

![In the Agents view sidebar, open Customize, then MCPs, then New MCP Server, then choose User](https://chartbuddy.io/images/cursor-mcp/03-customize-mcps.png)

Paste the Chartbuddy server block (toggle OS below), then save the file:

::: code-group

```json [Windows]
{
  "mcpServers": {
    "Chartbuddy-Hub": {
      "type": "stdio",
      "command": "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Chartbuddy\\chartbuddy.exe",
      "args": ["--mcp"]
    }
  }
}
```

```json [macOS]
{
  "mcpServers": {
    "Chartbuddy-Hub": {
      "type": "stdio",
      "command": "/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy",
      "args": ["--mcp"]
    }
  }
}
```

:::

![Paste the Chartbuddy config into the user mcp.json](https://chartbuddy.io/images/cursor-mcp/02-enter-mcp-json.png)

Prefer **one** global config. Duplicate global + project entries make it unclear which server the agent is using.

### 3. Refresh and use

**Refresh MCP** (or restart Cursor) and **enable Chartbuddy for the chat**. Mid-chat attach usually works after a refresh; if tools still do not appear, start a new agent chat.

## Verify

::: code-group

```powershell [Windows]
& "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp-status
```

```bash [macOS]
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status
```

:::

Exit `0` = Chartbuddy Hub bridge up. Keep Chartbuddy Hub running while you chart.

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp/claude.md
---

# Connect Claude (web)

This page is for **Claude in the browser** (claude.ai) and the **Home** tab in the Claude desktop app. **Claude Code** – including the **Code** tab in the Claude desktop app – uses a different setup. See [Connect Claude Code](https://chartbuddy.io/hub/docs/connect-mcp/claude-code.md).

::: warning Chartbuddy Hub MCP is not available here yet
Chartbuddy Hub connects over **local stdio MCP**. Claude in the browser and the desktop **Home** tab cannot reach a local Chartbuddy Hub process, and we do not ship a **remote MCP** endpoint yet – so regular Claude cannot connect to Chartbuddy Hub MCP today.
:::

## What you can use instead

| Option | Best for |
|--------|----------|
| **[Claude Code](https://chartbuddy.io/hub/docs/connect-mcp/claude-code.md)** | Full Chartbuddy Hub MCP in the terminal or the desktop **Code** tab |
| **[Embed docs](https://chartbuddy.io/embed/docs/getting-started.md)** | Charts inside Claude conversations via HTML artifacts and the `@chartbuddy.io/embed` widget |

For Embed, start with [`llms.txt`](https://unpkg.com/@chartbuddy.io/embed/llms.txt), then [Getting started](https://chartbuddy.io/embed/docs/getting-started.md) and [Visual QA](https://chartbuddy.io/embed/docs/quality-assurance/visual-qa.md) in the Embed docs.

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp/claude-code.md
---

# Connect Claude Code

Wire **Claude Code** (CLI) to Chartbuddy Hub over local stdio MCP.

## Setup via Chartbuddy Hub

1. Install Chartbuddy Hub and launch it once (approve OS security prompts).
2. Open **AI connections** in Hub (title-bar cable icon).

3) Connect **Claude Code**. Hub writes the server into your user Claude Code config.

4. Start a **new** Claude Code session (or run `/reload-plugins`) so tools load.

## Setup via prompting Claude

Prompt to paste into Claude Code:

```text
Set up the Chartbuddy Hub MCP server for this Claude Code install:

1. Detect my OS and find the Chartbuddy binary at its default install path:
   - macOS: /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy
   - Windows: %LOCALAPPDATA%\Programs\Chartbuddy\chartbuddy.exe
   If it's not there, ask me for the correct path. Don't guess or search the whole filesystem.

2. Check whether an MCP server named "chartbuddy" is already registered
   (`claude mcp list`). If it is, tell me and stop.

3. Register it as a user-scoped stdio MCP server:
   claude mcp add-json chartbuddy '{"type":"stdio","command":"<resolved path>","args":["--mcp"]}' --scope user

4. Confirm the Hub app is running and the bridge is reachable:
   <resolved path> --mcp-status
   (exit 0 = up, exit 1 = unreachable. If unreachable, tell me to launch
   Chartbuddy Hub first. Don't launch it yourself.)

5. Tell me to start a brand-new Claude Code session. MCP servers added
   mid-session aren't picked up.
```

## Setup via Terminal

Use **user** scope so the absolute binary path is not committed to a repo.

::: code-group

```powershell [Windows]
claude mcp add-json chartbuddy '{"type":"stdio","command":"C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Chartbuddy\\chartbuddy.exe","args":["--mcp"]}' --scope user
```

```bash [macOS]
claude mcp add-json chartbuddy '{"type":"stdio","command":"/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy","args":["--mcp"]}' --scope user
```

:::

Equivalent transport form:

::: code-group

```powershell [Windows]
claude mcp add --transport stdio chartbuddy --scope user -- "C:\Users\YOUR_USER\AppData\Local\Programs\Chartbuddy\chartbuddy.exe" --mcp
```

```bash [macOS]
claude mcp add --transport stdio chartbuddy --scope user -- "/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy" --mcp
```

:::

Then start a **new** Claude Code session – mid-session attach fails in Claude Code.

## Verify

::: code-group

```powershell [Windows]
& "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp-status
```

```bash [macOS]
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status
```

:::

Keep Chartbuddy Hub running while you chart.

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp/opencode.md
---

# Connect OpenCode

Wire **[OpenCode](https://opencode.ai)** to Chartbuddy Hub over local stdio MCP.

## Setup via Chartbuddy Hub

1. Install Chartbuddy Hub and launch it once (approve OS security prompts).
2. Open **AI connections** in Hub (title-bar cable icon).

3) Connect **OpenCode**. Hub writes the server into your global OpenCode config.

4. Restart OpenCode so tools load.

## Setup manually

Edit your **global** OpenCode config (`opencode.json` or `opencode.jsonc` – prefer global so the absolute Chartbuddy path is not committed to a repo):

* macOS / Linux: `~/.config/opencode/`
* Windows: `%USERPROFILE%\.config\opencode\`

Add a `Chartbuddy-Hub` entry under `mcp.servers`:

::: code-group

```json [Windows]
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "Chartbuddy-Hub": {
        "type": "local",
        "command": [
          "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Chartbuddy\\chartbuddy.exe",
          "--mcp"
        ]
      }
    }
  }
}
```

```json [macOS]
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "Chartbuddy-Hub": {
        "type": "local",
        "command": [
          "/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy",
          "--mcp"
        ]
      }
    }
  }
}
```

:::

Keep **Chartbuddy Hub** running. Restart OpenCode so tools load.

## Verify

::: code-group

```powershell [Windows]
& "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp-status
```

```bash [macOS]
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status
```

:::

Exit `0` = Chartbuddy Hub bridge up.

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp/antigravity.md
---

# Connect Google Antigravity

Wire **[Google Antigravity](https://antigravity.google)** to Chartbuddy Hub over local stdio MCP.

## Setup via Chartbuddy Hub

1. Install Chartbuddy Hub and launch it once (approve OS security prompts).
2. Open **AI connections** in Hub (title-bar cable icon).

3) Connect **Antigravity**. Hub writes the server into your global Antigravity MCP config.

4. Restart Antigravity or start a new conversation so tools load.

## Setup manually

Open **Manage MCP Servers → View raw config**, or edit the global MCP file directly:

* macOS / Linux: `~/.gemini/config/mcp_config.json`
* Windows: `%USERPROFILE%\.gemini\config\mcp_config.json`

Add a `Chartbuddy-Hub` entry under `mcpServers` (leave other servers untouched):

::: code-group

```json [Windows]
{
  "mcpServers": {
    "Chartbuddy-Hub": {
      "command": "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Chartbuddy\\chartbuddy.exe",
      "args": ["--mcp"]
    }
  }
}
```

```json [macOS]
{
  "mcpServers": {
    "Chartbuddy-Hub": {
      "command": "/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy",
      "args": ["--mcp"]
    }
  }
}
```

:::

Keep **Chartbuddy Hub** running. Restart Antigravity or start a new conversation so tools load.

If Antigravity reports that the command cannot be found, confirm Chartbuddy is installed at the path above (or use Hub's AI connections button to rewrite the entry).

## Verify

::: code-group

```powershell [Windows]
& "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp-status
```

```bash [macOS]
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status
```

:::

Exit `0` = Chartbuddy Hub bridge up.

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp/chatgpt-codex.md
---

# Connect ChatGPT / Codex

This page is for **Codex CLI** and the **Codex** tab in the ChatGPT desktop application. **ChatGPT (web)** – browser chat and regular chat in the desktop app – uses a different path. See [Connect ChatGPT (web)](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt.md).

## Setup via Chartbuddy Hub

1. Install Chartbuddy Hub and launch it once (approve OS security prompts).
2. Open **AI connections** in Hub (title-bar cable icon).

3) Connect **ChatGPT Desktop / Codex CLI**. Hub writes the server into your Codex user config.

4. Restart ChatGPT or Codex, then start a new Codex task so tools load.

## Setup manually

### 1. Open Settings

In the ChatGPT desktop app, click **Settings** in the **bottom-left** corner of the sidebar.

![Click Settings in the bottom-left of ChatGPT Desktop](https://chartbuddy.io/images/chatgpt-mcp/01-click-settings.png)

### 2. Plugins → MCPs

In the settings sidebar, open **Plugins** (under Integrations). Then open the **MCPs** tab.

![Open Plugins, then the MCPs tab](https://chartbuddy.io/images/chatgpt-mcp/02-plugins-then-mcps.png)

### 3. Add server

On the MCPs tab, click **+ Add server**.

![Click Add server on the MCPs tab](https://chartbuddy.io/images/chatgpt-mcp/03-add-server.png)

### 4. Enter the Chartbuddy details

Choose **Connect to a custom MCP** (STDIO). Fields appear in this order – fill in every row:

| Field | Value |
|-------|--------|
| **Name** | `Chartbuddy-Hub` (or `chartbuddy`) |
| **Type** | **STDIO** |
| **Command to launch** | Chartbuddy binary (see OS paths below) |
| **Arguments** | `--mcp` |
| **Environment variables** | leave empty |
| **Working directory** | leave the default |

**Command to launch:**

* macOS: `/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy`
* Windows: `C:\Users\YOUR_USER\AppData\Local\Programs\Chartbuddy\chartbuddy.exe` (replace `YOUR_USER`, or use the path shown after install)

Click **Save**.

![Enter Chartbuddy STDIO command and --mcp argument](https://chartbuddy.io/images/chatgpt-mcp/04-enter-details.png)

## After saving

1. Keep **Chartbuddy Hub** running.
2. Start a **new** Codex session and enable the Chartbuddy MCP server for that session if tools do not appear.
3. If ChatGPT asks to approve **network / loopback** for `chartbuddy`, approve it – the adapter must reach Chartbuddy Hub on `127.0.0.1`.
4. Optional check:

::: code-group

```powershell [Windows]
& "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp-status
```

```bash [macOS]
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status
```

:::

Exit `0` = Chartbuddy Hub is up.

## Troubleshooting

### Tool call blocked – “reasoning summaries” / organization verification

On the desktop **Codex** tab, Chartbuddy may be configured correctly and still fail when OpenAI’s automatic approval reviewer blocks the tool call – often with an error about **“reasoning summaries”** requiring organization verification. That comes from OpenAI’s approval / org settings, **not** from Chartbuddy or a bad MCP path.

**Options:**

1. Use **Codex CLI** instead of the desktop Codex tab (same MCP config, often fewer approval blockers), or
2. Verify your organization at [platform.openai.com/settings/organization/general](https://platform.openai.com/settings/organization/general), **or** switch to another editor – we recommend [Cursor](https://chartbuddy.io/hub/docs/connect-mcp/cursor.md), [Claude Code](https://chartbuddy.io/hub/docs/connect-mcp/claude-code.md), or [OpenCode](https://chartbuddy.io/hub/docs/connect-mcp/opencode.md).

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp/chatgpt.md
---

# Connect ChatGPT (web)

This page is for **ChatGPT in the browser** (chatgpt.com) and regular chat in the ChatGPT desktop app. **Codex** – including **Codex CLI** and the **Codex** tab in the ChatGPT desktop application – uses a different setup. See [Connect ChatGPT / Codex](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt-codex.md).

::: warning Chartbuddy Hub MCP is not available here yet
Chartbuddy Hub connects over **local stdio MCP**. ChatGPT in the browser and regular desktop chat cannot reach a local Chartbuddy Hub process, and we do not ship a **remote MCP** endpoint yet – so regular ChatGPT cannot connect to Chartbuddy Hub MCP today.
:::

## What you can use instead

| Option | Best for |
|--------|----------|
| **[ChatGPT / Codex](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt-codex.md)** | Full Chartbuddy Hub MCP in Codex CLI or the desktop **Codex** tab |
| **[Embed docs](https://chartbuddy.io/embed/docs/getting-started.md)** | Charts inside ChatGPT conversations via HTML artifacts and the `@chartbuddy.io/embed` widget |

For Embed, start with [`llms.txt`](https://unpkg.com/@chartbuddy.io/embed/llms.txt), then [Getting started](https://chartbuddy.io/embed/docs/getting-started.md) and [Visual QA](https://chartbuddy.io/embed/docs/quality-assurance/visual-qa.md) in the Embed docs.

---

---
url: https://chartbuddy.io/hub/docs/guides.md
---
# Guides

Workflow guides for Chartbuddy Hub — the desktop editor for AI-driven charting.

## Topics

* [Desktop basics](https://chartbuddy.io/hub/docs/guides/desktop-basics.md) — first launch, editing, and exporting
* [Push & pull](https://chartbuddy.io/hub/docs/guides/push-and-pull.md) — move charts between Hub and other surfaces
* [From Chrome extension](https://chartbuddy.io/hub/docs/guides/from-chrome-extension.md) — what carries over from the Slides extension

## Related docs

* [Embed docs](https://chartbuddy.io/embed/docs/getting-started.md) — JavaScript package for dashboards and products
* [Help Center](https://chartbuddy.io/help) — Google Slides end-user guides

---

---
url: https://chartbuddy.io/hub/docs/guides/desktop-basics.md
---
# Desktop basics

Chartbuddy Hub is your local chart editor. You operate it from your AI chat — Hub itself has no prompt box. MCP is the remote control; Hub is where charts live and get edited.

## First launch

1. Install Hub to **Applications** from the `.dmg`
2. Open Chartbuddy once (approve Gatekeeper if asked)
3. Confirm the bridge is up: the Hub `mcp-port` file should contain a port (macOS / Linux `~/.chartbuddy/mcp-port`, Windows `%USERPROFILE%\.chartbuddy\mcp-port`)
4. Connect your AI client — see [Connect MCP](https://chartbuddy.io/hub/docs/connect-mcp.md)

Leave Hub installed under `/Applications` so MCP auto-launch can find it.

## Typical workflow

1. **Prompt in AI** — ask Cursor, Claude, ChatGPT, or another MCP-connected client to create or update a chart
2. **Refine in Hub** — focus the chart window for pixel-level control (toolbar, spreadsheet panel, context menus)
3. **Push out** — send the live chart to Google Slides, Notion, Slack, or export as PNG
4. **Pull back** — grab a Chartbuddy PNG from another surface and pull it into Hub to edit again

## What Hub shares with the Chrome extension

Hub packs the same chart engine as the Chartbuddy for Google Slides™ extension:

* Waterfalls, mekkos, stacked bars, CAGRs, and the full business library
* Native editing — not a static screenshot
* Brand styling and number formats

The desktop shell adds push/pull, MCP integration, and a standalone window without a browser tab.

## Next

* [Connect MCP](https://chartbuddy.io/hub/docs/connect-mcp.md) — Cursor, ChatGPT, Claude, …
* [Push & pull](https://chartbuddy.io/hub/docs/guides/push-and-pull.md) — moving charts between surfaces

---

---
url: https://chartbuddy.io/hub/docs/guides/push-and-pull.md
---
# Push & pull

Hub is the bridge between AI-generated charts and the surfaces where you deliver work.

## Push

**Push** sends a live Chartbuddy chart out of Hub to another surface:

* Google Slides (native editor)
* Notion, Slack, email (as Chartbuddy PNG)
* Other destinations (expanding)

Charts stay alive where the destination supports native Chartbuddy editing (Slides today; PowerPoint soon).

## Pull

**Pull** brings a Chartbuddy chart back into Hub so you can edit it again:

1. Find a Chartbuddy PNG or chart artifact on another surface
2. Click and hold, drag to Hub, release
3. The chart becomes editable in the desktop app

Surfaces with a native Chartbuddy editor (Google Slides, PowerPoint) do not need pull-back — you edit there directly.

## When to use Hub vs Slides

| Scenario | Surface |
|----------|---------|
| Prompting from AI, quick iteration | Hub |
| Final deck in Google Workspace | Google Slides extension |
| Chart arrived as PNG in Slack/Notion | Pull into Hub |

::: info Placeholder
Step-by-step push/pull animations and supported MIME types will be documented here.
:::

---

---
url: https://chartbuddy.io/hub/docs/guides/from-chrome-extension.md
---
# From Chrome extension

Chartbuddy Hub is the desktop packaging of what already exists in the **Google Slides Chrome extension**.

## Shared engine

Both surfaces run the same charting core:

* Chart types: waterfall, mekko, stacked bar, line, stacked area, pie, scatter, combo, …
* Data model and styling defaults
* Native in-place editing

Hub does not replace the Slides extension — it complements it for AI-first workflows and desktop push/pull.

Agents can also drive the extension as a **chart head** of Hub over MCP (`surface: "ce"`, refs `ce:*`): Hub stays the single MCP entry; CE renders and edits in Slides. Internal vision + decisions: [`docs/ce-as-hub-head.md`](../../docs/ce-as-hub-head.md).

## What's different in Hub

| Chrome extension | Hub desktop |
|------------------|-------------|
| Lives inside Google Slides | Standalone desktop app |
| Sheets sync for deck data | MCP bridge for AI clients |
| OAuth to Google (in-browser tab) | System browser + localhost callback (PKCE) |
| SSO (WorkOS, work-email form) | Same WorkOS path; loopback + PKCE token exchange |
| Google account required | Email/password sign-in for users without Google or org SSO |
| Deck-native editing | Push/pull to multiple surfaces |

## Migration mental model

If you already use Chartbuddy in Slides, think of Hub as:

* The place AI agents send charts before they land in a deck
* The editor for charts that arrive as PNGs from chat or other tools
* The same chart quality, without opening a presentation

::: info Placeholder
Parity matrix (feature-by-feature) and shared keyboard shortcuts will be added as Hub ships.
:::

---

---
url: https://chartbuddy.io/hub/docs/README.md
---
# Chartbuddy Hub docs

VitePress source for **https://chartbuddy.io/hub/docs/**..md

This repo holds Hub documentation only. Hub installer / updater scripts stay in `chart-buddy` (`build/hub-release/`).

CI builds the site twice (`prod` / `acc`), baking `DOCS_ORIGIN` into agent-facing `.md` / `llms.txt` files, and publishes a tarball to this project's GitLab generic package registry. `chart_backend` downloads that tarball on deploy.

## Local

```bash
cd "2. Apps/4_hub_docs"
npm install
npm run dev
```

Sync into local Laravel (`http://localhost:8000/hub/docs/`):

```bash
DOCS_ORIGIN=http://localhost:8000 npm run sync
```

`sync` also copies agent files to `public/hub/llms.txt`, `mcp-setup.md`, and `mcp-setup.json`.

## Origins

| Environment | `DOCS_ORIGIN` |
| --- | --- |
| Local | `http://localhost:8000` |
| Acceptance | `https://cb-acc.xyz` |
| Production | `https://chartbuddy.io/` |

HTML keeps origin-relative `/hub/docs/...` links. Markdown twins get absolute URLs.

## Packages

Default-branch CI uploads:

* `hub-docs/prod/site.tar.gz`
* `hub-docs/acc/site.tar.gz`

`chart_backend` job `build_docs` / `build_docs_acceptance` unpacks the matching channel into `public/hub/docs/` (plus the `/hub/` agent files).

GitLab: https://gitlab.com/bytes22/hub-docs — CI uses hosted `saas-linux-small-amd64` runners. Allow inbound job tokens from `bytes22/chart_backend` (or set `DOCS_PACKAGE_TOKEN` there).