# Developer guide

> Contribution guidelines for building and adding features to GenAIScript

GenAIScript welcomes contributions from the community. This document provides guidelines for setting up the development environment, building the project, and contributing to the codebase.

## Setup

[Section titled “Setup”](#setup)

You can open this repo in GitHub CodeSpace/Docker to get the build environment needed.

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true\&ref=main\&repo=679784368)

* Go to <https://github.com/microsoft/genaiscript>
* Click on **Code**
* Select Create new Codespace
* Select the **dev** branch

### Manual setup

[Section titled “Manual setup”](#manual-setup)

* Install [Node.JS LTS](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
* Run yarn

```sh
pnpm install --frozen-lockfile --prefer-offline
```

## Build

[Section titled “Build”](#build)

You can do a full compile using esbuild.

```sh
pnpm build
```

or just the cli

```sh
pnpm build:cli
```

## Pull Requests

[Section titled “Pull Requests”](#pull-requests)

You must create pull requests against the `dev` branch. The `main` branch is reserved for releases. The `dev` branch is the main development branch. It is where all new features and bug fixes are merged before being released to the public.

When creating a pull request, please ensure that your code adheres to the following guidelines:

* Follow the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
* Ensure that your code is well-documented and follows the project’s coding style.
* If possible, add tests for any new features or bug fixes.

## Running local scripts

[Section titled “Running local scripts”](#running-local-scripts)

To run a script using the locally built cli,

```sh
pnpm genai <scriptid> ...
```

To run a sample script under the `samples/sample` folder:

```sh
pnpm run:script <scriptid> ...
```

In this case, it will use the `samples/sample/.env` file for the environment variables and workspace will be rooted at `samples/sample`.

## Debugging local scripts

[Section titled “Debugging local scripts”](#debugging-local-scripts)

Open a `JavaScript Debug Terminal` and launch the script using

```sh
pnpm genai:debug <scriptid> ...
```

or for samples

```sh
pnpm run:script:debug <scriptid> ...
```

## Logging

[Section titled “Logging”](#logging)

GenAIScript uses the [debug](https://www.npmjs.com/package/debug) library for logging. You can enable logging by setting the `DEBUG` environment variable to `genai:*`.

```sh
DEBUG=genaiscript:* pnpm genai <scriptid> ...
```

## Web viewer

[Section titled “Web viewer”](#web-viewer)

The web application (React 19) is meant to run both as a Visual Studio Code panel and a standalone viewer (**playground**). For testing purposes, standalone is the easiest.

* React 19, currently very little dependencies
* react-markdown + a few plugins to run the markdown
* [vscode-elements](https://vscode-elements.github.io/) is the design system we use as it mimics the vscode look and feel.

Use the following command to start the local web server:

```sh
pnpm serve
```

It will start a local server and rebuild the react client on file changes. **It will not rebuild/restart the server on changes.** There is **no** hot reload, you need to refresh the browser. If some state should be serialized, we should start adding it to the hash.

## Visual Studio Code Extension development

[Section titled “Visual Studio Code Extension development”](#visual-studio-code-extension-development)

Working on the VSCode involves launching the main project debugger, which opens a second VSCode instance with the GenAIScript extension.

You can set debug breakpoint anywhere in the GenAIScript typescript files and they will resolve.

* uninstall the official GenAIScript extension or it will clash with the locally built one
* open the `Debug` view in Vs Code
* select the **Samples** debugger configuration and click **Run**

Remember that the debugger is only attached to the extension; not the GenAIScript server.

### Caveats

[Section titled “Caveats”](#caveats)

Launching the debugger sometimes fails but still unknown reasons. To work around this, open a terminal and run `pnpm build` once. Then launch the debugger again.

## Docs

[Section titled “Docs”](#docs)

Run `docs` to launch the documentation site.

```sh
pnpm docs
```

Run this command to catch broken links

```sh
pnpm build:docs
```

## Slides

[Section titled “Slides”](#slides)

All files `slides/*slides.md` will be compiled and deployed on build.

* run `slides` to launch the slide show (add the file name or it will default to `slides.md`)

```sh
pnpm slides [slides file name]
```

Learn more about Slidev on [documentations](https://sli.dev/). For diagrams, leverage [mermaid](https://sli.dev/guide/syntax#diagrams) or use draw\.io, tldraw.

## GenAIScripts

[Section titled “GenAIScripts”](#genaiscripts)

* Commit with auto-generated message

```sh
pnpm gcm
```

* Add doc to new or updated apis

```sh
pnpm genai:docs
```

* Generate images for blog posts

```sh
pnpm genai:blog-images
```

## Packaging

[Section titled “Packaging”](#packaging)

To compile and package the Visual Studio Code extension, run the `package` script.

```sh
pnpm package
```

You will find the built package files, `genaiscript.vsix`, in the `packages/vscode` folder.

## Release

[Section titled “Release”](#release)

Run the `release` script.

```sh
pnpm release
```

GitHub Pages are automatically updated on new release; or through manual trigger at <https://github.com/microsoft/genaiscript/actions/workflows/docs.yml> .

## Contributing

[Section titled “Contributing”](#contributing)

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact <opencode@microsoft.com> with any additional questions or comments.

## MCP Server Testing

[Section titled “MCP Server Testing”](#mcp-server-testing)

### Testing HTTP Transport Locally

[Section titled “Testing HTTP Transport Locally”](#testing-http-transport-locally)

To test the HTTP transport locally, follow these steps:

1. **Start the HTTP MCP server** in one terminal:

```sh