node-gptscript

Fork notice / Attribution

This repository is a fork of node-gptscript, originally developed by Acorn Labs, Inc. (now Obot Inc.) and the gptscript-ai contributors. The upstream project has been archived. This fork is maintained by BasePeak GmbH at https://git.basepeak.dev/basepeak-ai/node-gptscript.

BasePeak GmbH has modified files in this repository since the fork on 2026-06-13. The git history records every change. See NOTICE for details.

This module provides a set of functions to interact with gptscripts. It allows for executing scripts, listing available tools and models, and more. The functions are designed to be used in a Node.js environment.

Installation

To use this module, you need to have Node.js installed on your system.

This fork is not published to the npm registry. The @gptscript-ai/gptscript package on npmjs.com is the archived upstream release, not this fork. Install the fork from git instead:

npm install git+https://git.basepeak.dev/basepeak-ai/node-gptscript.git

The package keeps the name @gptscript-ai/gptscript, so imports are unchanged. Installing from git builds the module (prepare) and runs a postinstall script that downloads the gptscript binary from the gptscript fork's releases into the node_modules/@gptscript-ai/gptscript/bin directory. The release downloads are public, so no token is needed. GPTSCRIPT_RELEASE_TOKEN is optional: when set, it is sent as a Forgejo token with the download request.

You can opt out of the binary download by setting the NODE_GPTSCRIPT_SKIP_INSTALL_BINARY=true environment variable before running npm install, and point GPTSCRIPT_BIN at an existing binary instead.

Usage

To use the module and run gptscripts, you need to first set the OPENAI_API_KEY environment variable to your OpenAI API key. You can also set the GPTSCRIPT_BIN environment variable to change the execution of the gptscripts.

To ensure the binary is installed properly, you can run the following command:

npx --no-install gptscript --version

You will see the installed gptscript version in the output of the command.

GPTScript

The GPTScript instance allows the caller to run gptscript files, tools, and other operations (see below). Note that the intention is that a single instance is all you need for the life of your application, you should call close() on the instance when you are done.

Global Options

When creating a GTPScript instance, you can pass the following global options. These options are also available as run Options. Except Env, anything specified as a run option will take precedence over the global option. Any env provided in the run options are appended.

• APIKey: Specify an OpenAI API key for authenticating requests
• BaseURL: A base URL for an OpenAI compatible API (the default is https://api.openai.com/v1)
• DefaultModel: The default model to use for chat completion requests
• DefaultModelProvider: The default model provider to use for chat completion requests
• Env: Replace the system's environment variables with these in the for KEY=VAL

Run Options

These are optional options that can be passed to the various exec functions. None of the options is required, and the defaults will reduce the number of calls made to the Model API. As noted above, the Global Options are also available to specify here. These options would take precedence.

• cache: Enable or disable caching. Default (true).
• cacheDir: Specify the cache directory.
• quiet: No output logging
• subTool: Use tool of this name, not the first tool
• input: Input arguments for the tool run
• workspace: Directory to use for the workspace, if specified it will not be deleted on exit
• chatState: The chat state to continue, or null to start a new chat and return the state
• confirm: Prompt before running potentially dangerous commands
• prompt: Allow scripts to prompt the user for input
• env: Extra environment variables to pass to the script in the form KEY=VAL

Functions

listModels

Lists all the available models, returns a list.

Usage:

const gptscript = require('@gptscript-ai/gptscript');

async function listModels() {
    let models = [];
    const g = new gptscript.GPTScript();
    try {
        models = await g.listModels();
    } catch (error) {
        console.error(error);
    }
    g.close();
}

version

Get the first of the current gptscript binary being used for the calls.

Usage:

const gptscript = require('@gptscript-ai/gptscript');

async function version() {
    const g = new gptscript.GPTScript();
    try {
        console.log(await g.version());
    } catch (error) {
        console.error(error);
    }
    g.close();
}

evaluate

Executes a prompt with optional arguments. The first argument can be a ToolDef, an array of ToolDefs, or a string representing the contents of a gptscript file.

const gptscript = require('@gptscript-ai/gptscript');

const t = {
    instructions: "Who was the president of the united states in 1928?"
};

const g = new gptscript.GPTScript();
try {
    const run = await g.evaluate(t);
    console.log(await run.text());
} catch (error) {
    console.error(error);
}
g.close();

run

Executes a GPT script file with optional input and arguments. The script is relative to the callers source directory.

const gptscript = require('@gptscript-ai/gptscript');

const opts = {
    disableCache: true,
    input: "--input World"
};

async function execFile() {
    const g = new gptscript.GPTScript();
    try {
        const run = await g.run('./hello.gpt', opts);
        console.log(await run.text());
    } catch (e) {
        console.error(e);
    }
    g.close();
}

Getting events during runs

The Run object exposes event handlers so callers can access the progress events as the script is running.

The Run object exposes these events with their corresponding event type:

Subscribing to RunEventType.Event gets you all events.

const gptscript = require('@gptscript-ai/gptscript');

const opts = {
    disableCache: true,
    input: "--testin how high is that there mouse?"
};

async function streamExecFileWithEvents() {
    const g = new gptscript.GPTScript();
    try {
        const run = await g.run('./test.gpt', opts);

        run.on(gptscript.RunEventType.Event, data => {
            console.log(`event: ${JSON.stringify(data)}`);
        });

        await run.text();
    } catch (e) {
        console.error(e);
    }
    g.close();
}

Confirm

If a gptscript can run commands, you may want to inspect and confirm/deny the command before they are run. This can be done with the confirm method. A user should listen for the RunEventType.CallConfirm event.

const gptscript = require('@gptscript-ai/gptscript');

const opts = {
    disableCache: true,
    input: "--testin how high is that there mouse?",
    confirm: true
};

async function streamExecFileWithEvents() {
    const g = new gptscript.GPTScript();
    try {
        const run = await g.run('./test.gpt', opts);

        run.on(gptscript.RunEventType.CallConfirm, async (data: gptscript.CallFrame) => {
            // data.Tool has the information for the command being run.
            // data.Input has the input for this command

            await g.confirm({
                id: data.id,
                accept: true, // false if the command should not be run
                message: "", // Explain the denial (ignored if accept is true)
            })
        });

        await run.text();
    } catch (e) {
        console.error(e);
    }
    g.close();
}

Prompt

A gptscript may need to prompt the user for information like credentials. A user should listen for the RunEventType.Prompt. Note that if prompt: true is not set in the options, then an error will occur if a gptscript attempts to prompt the user.

const gptscript = require('@gptscript-ai/gptscript');

const opts = {
    disableCache: true,
    input: "--testin how high is that there mouse?",
    prompt: true
};

async function streamExecFileWithEvents() {
    const g = new gptscript.GPTScript();
    try {
        const run = await g.run('./test.gpt', opts);

        run.on(gptscript.RunEventType.Prompt, async (data: gptscript.PromptFrame) => {
            // data will have the information for what the gptscript is prompting.

            await g.promptResponse({
                id: data.id,
                // response is a map of fields to values
                responses: {[data.fields[0]]: "Some Value"}
            })
        });

        await run.text();
    } catch (e) {
        console.error(e);
    }
    g.close();
}

Chat support

For tools that support chat, you can use the nextChat method on the run object to continue the chat. This method takes a string representing the next chat message from the user.

If the chat can/should continue, then the Run's state will be RunState.Continue. Note that calling nextChat on a Run object is an error. Each call to nextChat will return a new Run instance, so, the call can keep track of the chat Runs, if desired.

Here is an example flow for chat.

const gptscript = require('@gptscript-ai/gptscript');

const opts = {
    disableCache: true
};

const t = {
    chat: true,
    tools: ["sys.chat.finish"],
    instructions: "You are a chat bot. Don't finish the conversation until I say 'bye'."
};

async function streamExecFileWithEvents() {
    const g = new gptscript.GPTScript();
    let run = await g.evaluate(t, opts);
    try {
        // Wait for the initial run to complete.
        await run.text();

        while (run.state === gptscript.RunState.Continue) {
            // ...Get the next input from the user somehow...

            run = run.nextChat(inputFromUser)

            // Get the output from gptscript
            const output = await run.text()

            // Display the output to the user...
        }
    } catch (e) {
        console.error(e);
    }

    g.close();

    // The state here should either be RunState.Finished (on success) or RunState.Error (on error).
    console.log(run.state)
}

Types

Tool Parameters

Argument	Type	Default	Description
name	string	""	The name of the tool. Optional only on the first tool if there are multiple tools defined.
description	string	""	A brief description of what the tool does, this is important for explaining to the LLM when it should be used.
tools	array	[]	An array of tools that the current tool might depend on or use.
maxTokens	number/undefined	undefined	The maximum number of tokens to be used. Prefer undefined for uninitialized or optional values.
modelName	string	""	The model that the tool uses, if applicable.
cache	boolean	true	Whether caching is enabled for the tool.
temperature	number/undefined	undefined	The temperature setting for the model, affecting randomness. undefined for default behavior.
args	object	{}	Additional arguments specific to the tool, described by OpenAPIv3 spec.
internalPrompt	boolean	false	An internal prompt used by the tool, if any.
instructions	string	""	Instructions on how to use the tool.
jsonResponse	boolean	false	Whether the tool returns a JSON response instead of plain text. You must include the word 'json' in the body of the prompt
export	string[]	[]	A list of tools exported by this tool

License

Copyright (c) 2024-2025 Obot Inc. (formerly Acorn Labs, Inc.) (original work)

Modifications Copyright (c) 2026 BasePeak GmbH

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.