Editing a Retool Classic app with an external coding agent

🧑‍💻 Retool Tips & Tricks
,
1

:double_exclamation_mark:Disclaimer: External Toolscript edits are possible, but we recommend building Classic apps in the Retool editor and using the new app builder for natural language development.

Overview

This guide explains how to work on a Retool Classic (Toolscript) app with an external coding agent (e.g. Cursor, Codex, Claude). The key step is to update Retool after changing a branch directly in Git. Otherwise, a later Retool commit can overwrite those changes.

Prerequisites

  • A Retool Enterprise plan with API access and Source Control enabled.

  • A Source Control protected app connected to your Git repository.

  • Permission to edit the app and its Git branch.

  • Enable Enable branch merging (Settings → Beta)

The documented building path is best used for making targeted edits to existing apps, or to interrogate how your app works/is constructed.

The key idea

A source controlled app has two copies of a branch: the version in Retool’s editor and the version in Git. Edits made in Retool are committed to Git, but changes pushed directly to Git do not automatically appear in Retool’s editor. After an external change, reset the branch in Retool before making another Retool change.

Pushing to Git does not update Retool’s editor copy. Reset the branch before your next Retool edit or commit.

Workflow

  1. Create the branch in Retool. In the app editor, click the branch name in the lower left, select Create branch, and name it. Make and commit a small change in Retool, then confirm the branch appears in your Git repository before checking it out locally.
  2. Work locally. Clone the connected repository, check out the same branch, and give your coding agent a specific task. Ask it to inspect the existing Toolscript structure and change only the files needed.
  3. Review and push. Inspect the agent’s diff for unintended changes, validate Toolscript, then commit and push the branch to Git.
  4. Sync Retool from Git. In the Retool app editor, open the feature branch and select Branch menu → ••• → Reset branch. Do this before editing or committing on that branch in Retool.
  5. Verify in Retool. After resetting, confirm the app loads and works as intended. An agent may write malformed or non-canonical Toolscript, and Retool may rewrite it when you next commit from the editor. Review that commit’s diff for unexpected changes before merging

Repeat steps 2–5 whenever the agent pushes another change.

Keeping the branch current

If main advances, use Retool’s Merge main into <branch> action. It is available when Settings → Beta → Enable branch merging is on. If you merge, rebase, or cherry-pick through Git instead, reset the branch in Retool afterward. The same rule applies to any other change made directly to the Git branch. Retool’s branch merging guide explains the in-product merge flow.

3 Likes
Assist Beta Conclusion