create_branch

Create a new git branch in a project. Use this to start a scenario branch for testing alternative assumptions. Scenario workflow: (1) create_branch to start the scenario, (2) patch_file for small edits or update_file for larger changeson the scenario branch, (3) compare_branches to run both branches and diff the outputs, (4) merge_branch (Owner only) to adopt the winning scenario into main, or create_pull_request for team review before merging.

Parameters

Name	Type	Required	Default	Description
project_name	Annotated[str, Field(description='Name of the Bridge Town project.')]	Yes	—
branch_name	Annotated[str, Field(description='Name for the new branch. Must be a valid git ref name (no spaces, no special chars except hyphens and underscores).')]	Yes	—
base_branch	Annotated[str, Field(description="Branch to create from. Defaults to 'main'.")]	No	'main'

Returns

Returns a structured object. Top-level fields:

• project (string)
• branch (string)
• base_branch (string)
• sha (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "create_branch",
  "arguments": {
    "project_name": "forecasts",
    "branch_name": "scenario/aggressive-growth",
    "base_branch": "main"
  }
}

Response

{
  "project": "forecasts",
  "branch": "scenario/aggressive-growth",
  "base_branch": "main",
  "sha": "abc1234def5678901234567890abcdef12345678"
}

Notes

• Module: Branches
• Requires authentication via API token or Auth0 JWT.