Read-only tools

gs_status

Start here. Returns the full stack state as structured JSON. Use this as your first call to orient yourself. Includes a summary of which branches need restacking.

Parameters: none
Returns: {trunk, current_branch, initialized, summary: {total_branches, needs_restack[]}, branches[]}
When to use: First call to understand the stack. Prefer over gs_log unless you need commit history.

gs_branch_info

Get detailed info about a single branch including its commits and whether it needs restacking.

Parameters: branch (string, required)
Returns: {name, parent, children[], commits[], depth, is_current, is_trunk, needs_restack}
When to use: After gs_status to inspect a specific branch. If needs_restack is true, call gs_restack with scope "only".

gs_log

Get the stack tree with optional commit history for every branch. Superset of gs_status.

Parameters: include_commits (bool, optional -- default: false)
Returns: {trunk, current_branch, branches[]}
When to use: When you need to see what commits each branch contains (e.g., before a large restack). Without include_commits, response is nearly identical to gs_status.

gs_diff

Get the unified diff for a branch compared to its parent. Shows only changes introduced by this branch.

Parameters: branch (string, optional -- defaults to current)
Returns: {branch, parent, diff}
When to use: Before deciding to modify, fold, or submit a branch. Cannot diff trunk.
Next steps: gs_modify to amend, gs_fold to squash into parent, gs_create to add a follow-up branch.

Navigation tools

gs_checkout

Switch to a specific branch by name. Works with any git branch, including untracked ones.

Parameters: branch (string, required)
Returns: {previous_branch, current_branch}
When to use: When you know the exact branch name. For relative movement, use gs_navigate.

gs_navigate

Move through the stack along parent-child edges.

Parameters: direction (enum: up/down/top/bottom), steps (int, optional -- default: 1, only for up/down)
Returns: {previous_branch, current_branch, steps_taken} or {error: "ambiguous_navigation", options[]} when multiple children exist
Direction meanings: down = toward trunk, up = toward leaves, bottom = jump to trunk, top = jump to leaf
When to use: For relative stack movement. Use gs_checkout when you know the target branch name.

Mutation tools -- branch lifecycle

gs_create

Create a new stacked branch on top of the current branch. Switch to the desired parent first.

Parameters: name (string, required), commit_message (string, optional)
Returns: {branch, parent, commit_created}
When to use: Starting new work that depends on the current branch. Call repeatedly to build a stack.

gs_delete

Delete a branch from the stack and git. Children are automatically reparented.

Parameters: branch (string, required)
Returns: {deleted, reparented_children[], new_parent, checked_out?}
When to use: Cleaning up merged or abandoned branches. Follow with gs_restack scope "all" to rebase reparented children.

gs_track

Start tracking an existing git branch in the stack. Use to adopt branches created outside gs.

Parameters: branch (string, required), parent (string, required)
Returns: {branch, parent}
When to use: After someone creates a branch with plain git checkout -b. Follow with gs_restack scope "only" to align it.

gs_untrack

Stop tracking a branch. The git branch is not deleted.

Parameters: branch (string, required)
Returns: {branch, warnings[]}
When to use: Removing a branch from gs without deleting it. Children become orphaned -- reparent with gs_move first, or use gs_delete instead.

gs_rename

Rename the current branch. Updates all metadata references automatically.

Parameters: new_name (string, required)
Returns: {old_name, new_name}
When to use: Before submitting a PR, or to fix naming. Switch to the branch first with gs_checkout.

Mutation tools -- stack operations

gs_restack

Rebase branches to align with their declared parents. The key operation for stack consistency.

Parameters: branch (string, optional -- defaults to current), scope (enum: only/upstack/downstack/all -- default: all)
Returns: {restacked[], skipped[], conflict?}
Scope meanings: only = single branch, upstack = branch + descendants, downstack = ancestors to trunk, all = entire stack
When to use: After gs_modify, gs_move, gs_delete, or pulling upstream changes. Prerequisite: clean working tree.

gs_modify

Amend the current branch's last commit (or create a new one) and restack direct children.

Parameters: message (string, optional), new_commit (bool, default: false), stage_all (bool, default: false)
Returns: {branch, action, restacked_children[]}
When to use: After making changes to the current branch. Only direct children are restacked -- for deeper stacks, follow with gs_restack scope "upstack".

gs_move

Move a branch to a new parent, rebasing onto the target.

Parameters: branch (string, optional -- defaults to current), onto (string, required)
Returns: {branch, old_parent, new_parent}
When to use: Reorganizing the stack. Descendants are NOT automatically restacked -- follow with gs_restack scope "upstack".

gs_fold

Squash-merge the current branch into its parent. Children are reparented. Branch is deleted unless keep=true.

Parameters: keep (bool, default: false)
Returns: {folded, into, kept, reparented_children[]}
When to use: Collapsing completed work into the parent. Individual commit history is lost. Follow with gs_restack scope "upstack" on the parent to rebase reparented children.

Sync tools

gs_sync

Fetch remote, sync trunk, restack.

Parameters: force (bool, optional), restack (bool, optional)

gs_submit

Create/update PRs for branches.

Parameters: branch (string, optional), scope (enum: current/stack)

MCP Tools Reference