Threads and branches

How threads and branches work in the app builder.

When you build apps using the Chat tab in the app builder, your work is organized in two ways: by thread, and by branch. This page explains the distinction and provides best practices for working with threads and branches.

Threads

A thread is a single chat conversation with the agent in the Chat tab. Threads are intended to help you keep your work organized by task or theme. For example, use one thread for updating your app theme, and another thread for editing a chart on that page.

The new thread lives on your current branch and builds on previous changes, while your other threads on the branch remain available.

Each thread has a context window that fills up as you prompt. When you're close to the limit, Retool automatically compacts the conversation so you can keep working in the same thread.

Manage threads

Manage threads from the Chat tab of the app builder. To the left of the prompting box, click + to create a new thread.

Click to switch between threads on the current branch. Switching threads while the agent is working cancels the active generation.

Each thread is a different conversation about the same app preview, so switching between threads keeps your changes and the app preview in place.

Branches

A branch is a set of changes to your app, associated with an app preview, and with its own version history. A branch is the unit of work that you publish, and you create a new branch to begin a distinct line of work. For example, create a new branch when you want to change the resources that your app uses, or when you want to overhaul a page.

Each branch can have one or multiple threads.

Manage branches

Manage branches from the Version history tab in the navbar. Create a new branch by clicking +. Creating a new branch initiates a new set of changes based off the app's most recent published version.

Switch between existing branches under the Changes in progress section. Selecting a branch opens its most recent thread.

Branches are collaborative. Builders can view all other open branches and their associated threads.

Publishing branches

When all changes on your branch are complete, publish your app. Publishing your app archives the relevant branch, which is then marked with .

You can reopen your archived branch by continuing to prompt in the thread, or creating a new thread.

Branches in protected apps

When using Source Control, branches in the protected app builder map to branches in your external git repository. Multiple threads can contribute to the same branch, and publishing the branch reflects its changes in your repository.