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

# Runchat for Archicad

> Runchat for Archicad. Build and run AI workflows inside Archicad, capture viewport screenshots as workflow inputs, and run Python scripts against your model.

# Getting Started

Runchat for Archicad integrates the full Runchat web app directly into Archicad through a dockable palette. Capture viewport screenshots as inputs to AI workflows and run Python scripts that read and analyze your model — without leaving Archicad.

## Install the Add-On

Requires **Archicad 29** on **Windows**.

<Card title="Download Runchat for Archicad" icon="download" href="https://storage.runchat.app/runchat-archicad-latest.apx">
  Add-On for Archicad 29 (Windows)
</Card>

<Steps>
  <Step title="Add in Archicad">
    Open Archicad → **Options** → **Add-On Manager** → **Edit List of
    Available Add-Ons** → **Add** and select the downloaded
    `Runchat.apx` file.
  </Step>

  <Step title="Enable">
    Make sure the checkbox next to **Runchat** is ticked, then click **OK**.
  </Step>

  <Step title="Restart Archicad">
    Restart Archicad so it can build the Runchat menu. The **Runchat** menu
    only appears after a restart.
  </Step>

  <Step title="Open the palette">
    Choose **Runchat** → **Runchat Palette**. Log in with your Runchat account
    and you're ready to go.
  </Step>
</Steps>

## Bridge capabilities

The palette runs the full Runchat web app and communicates with Archicad through a local bridge.

* **Viewport capture**: Send the active Archicad window (plan, section, or 3D) as an image input to AI workflows, or let the agent take screenshots to verify its work.
* **Python scripts**: Code nodes set to **ArchiCAD Python** run against your live model through the official Archicad JSON API — list and filter elements, read properties, classifications, stories, and bounding boxes, and feed results into workflows.

## Running scripts

Scripts use the official [`archicad` Python package](https://pypi.org/project/archicad/) and run in a local Python process. One-time setup:

<Steps>
  <Step title="Install Python 3">
    Install Python 3 from [python.org](https://www.python.org/downloads/) if
    you don't already have it (tick "Add python.exe to PATH" in the
    installer).
  </Step>

  <Step title="Install the archicad package">
    In a terminal, run: `pip install archicad`
  </Step>

  <Step title="Enable the JSON connection">
    In Archicad, make sure the JSON/Python interface is enabled so scripts can
    connect (Options → Work Environment).
  </Step>
</Steps>

Scripts get a live connection preloaded — `conn`, `acc` (commands), `act` (types), and `acu` (utilities) — and anything you `print()` becomes the node output.

<Note>
  The official Archicad JSON API is read and analysis focused: scripts can
  query elements, properties, and project structure, but cannot create
  geometry. Extended commands are on the roadmap.
</Note>

## Updates

The palette checks for updates automatically when it loads. If a newer version is available, you'll see a banner at the top of the panel with a download link. Install the new `.apx` over the old one via the Add-On Manager.

## Troubleshooting

<AccordionGroup>
  <Accordion title="No Runchat menu after install">
    **Restart Archicad after adding the add-on** — the Runchat menu only shows
    up once Archicad rebuilds its menus on the next launch. If it's still
    missing, check the add-on is enabled in **Options** → **Add-On Manager**
    and that you downloaded the version matching your Archicad version
    (currently Archicad 29, Windows).
  </Accordion>

  <Accordion title="Script nodes fail with 'Python was not found'">
    Install Python 3 and make sure `python.exe` is on your PATH, or set the
    `RUNCHAT_PYTHON` environment variable to the full path of a python.exe.
  </Accordion>

  <Accordion title="Script nodes fail with 'archicad package is not installed'">
    Run `pip install archicad` in a terminal using the same Python
    installation the plugin found.
  </Accordion>

  <Accordion title="Scripts can't reach the Archicad JSON API">
    Enable the JSON/Python connection in Archicad's settings and retry. If you
    have multiple Archicad instances open, scripts connect to the first one
    that responds — close extra instances if the wrong project is targeted.
  </Accordion>

  <Accordion title="Login problems in the palette">
    If a third-party sign-in provider refuses to load inside the embedded
    browser, sign in with your email and password instead.
  </Accordion>
</AccordionGroup>

## Need Help?

* **Community**: [Join our Discord](https://discord.gg/2KXUBZNZ4e) for help and inspiration