Manage branches

Use branches whenever changes need review before they become part of main.

Create a branch

tiden branch create \
  --product-id <product-id> \
  --name intent/checkout-refactor \
  --description "Review checkout specs captured from the agent session."

Branch names must be lowercase and may contain letters, numbers, slashes, underscores, and hyphens.

Work on a branch

Pass --branch to branch-aware commands:

tiden spec list --product-id <product-id> --branch intent/checkout-refactor

tiden spec create \
  --product-id <product-id> \
  --branch intent/checkout-refactor \
  --title "Checkout applies coupons" \
  --content "..."

Tests also support branch operations:

tiden test list --product-id <product-id> --branch intent/checkout-refactor

Preview merge

tiden branch merge-preview \
  --product-id <product-id> \
  --name intent/checkout-refactor

Review additions, modifications, deletions, conflicts, duplicates, and link proposals in the web UI or in the command's output before merging. A duplicate is a suite or case the branch created that already exists on main; the merge adds it as a second copy. See Merge preview for how duplicates are matched and how to remove one without losing the cases under it.

Review link proposals

List proposals:

tiden branch link-proposals list \
  --product-id <product-id> \
  --name intent/checkout-refactor \
  --status proposed

Accept all proposed links:

tiden branch link-proposals review \
  --product-id <product-id> \
  --name intent/checkout-refactor \
  --decision accepted \
  --all-proposed

Reject a specific proposal:

tiden branch link-proposals review \
  --product-id <product-id> \
  --name intent/checkout-refactor \
  --decision rejected \
  --proposal-id <proposal-id> \
  --note "Spec changed scope."

Merge

tiden branch merge \
  --product-id <product-id> \
  --name intent/checkout-refactor

To merge only the preview you reviewed, copy the Digest: line from the tiden branch merge-preview output and pass it to the merge:

tiden branch merge \
  --product-id <product-id> \
  --name intent/checkout-refactor \
  --expect-preview <digest>

If the branch changed after the preview, Tiden refuses the merge with MERGE_PREVIEW_STALE and merges nothing. Preview the branch again, review it, and merge with the new digest. See Merge only the reviewed preview.

Auto-resolve conflicts only when your team has a clear policy:

tiden branch merge \
  --product-id <product-id> \
  --name intent/checkout-refactor \
  --auto-resolve branch

List what a merge changed

After a branch merges, list what it put into main:

tiden branch merged-changes \
  --product-id <product-id> \
  --name intent/checkout-refactor

Add --format json for a script.

Let Tiden merge an intent branch

Tiden merges a finished intent branch into main by itself, about 24 hours after the last pull request of that work merges. You do not run tiden branch merge for it. The rules, the closing pass, and what happens to partly delivered and abandoned work are on the Branches page.

Open the branch to see where it stands. The merge box shows one of these:

The merge box says	What it means
Merges automatically after a time	The 24 hours are counting. When the branch still waits for something, the line names it: an open pull request or an active agent session. For an open pull request it also shows the date Tiden stops waiting for it if nothing happens.
On hold until a date	A hold is set. The line shows who set it and why, and offers Release hold.
Partially delivered	Some promises are still open. The box lists them and shows the date the shipped part merges.
Abandoned	No pull request merged and 7 days passed without activity. An open pull request with no activity for 7 days does not keep the branch open. Any activity reopens the branch, and so does a linked pull request that merges later.
Merged automatically by Tiden	The merge ran. Flags under it show a red Quality Gate, resolved conflicts, or a skipped closing pass.
Checkpoint merge	The shipped part of a partly delivered intent merged. The box links to the successor.
Automatic merge is off for this product	The product setting is off. Nothing merges or is abandoned by itself.

You can still merge by hand at any time. A manual merge does not wait for the 24 hours.

Hold an automatic merge

Set a hold when more pull requests for the same intent are coming, or when you want to review the branch before it merges. A hold stops every timer of the automatic merge until it ends.

From the CLI:

tiden intent hold --for 7d --reason "Pull request 2 is next"

• --for takes days or hours, such as 3d or 12h. The default is 7d. --until <date> sets an end date instead.
• --reason is required. Your team reads it on the branch page.
• A hold an agent sets lasts at most 7 days. A person can hold an intent for up to 30 days. Tiden refuses an end date in the past or beyond the limit, and shows the reason.
• --intent <branch> or --session <id> names the intent. Without either, the command uses the active session of the current repository.

From the web app, open the branch and select Hold for 7 days. Tiden asks for a reason. Coding agents can also call the MCP tool hold_intent; their hold lasts at most 7 days. To hold an intent longer, hold it yourself. The working contract that tiden intent start prints tells an agent to set a hold before it hands back when more pull requests are planned.

When the hold ends, Tiden checks the intent again. The 24 hours, the 7 days for partly delivered work, and the 7 days for abandonment all count from the end of the hold.

A hold on an abandoned intent reopens it. A merged branch cannot be held: tiden intent hold exits with code 3 and points to tiden intent reopen, which starts a new intent that continues the merged one.

Release a hold

Release a hold when you no longer need it:

tiden intent hold --clear --intent intent/checkout-refactor

In the web app, select Release hold on the branch. Tiden checks the intent at once. The timers count from the moment you release, so the 24 hours start then.

Continue a partly delivered intent

A partly delivered intent keeps its open promises on the branch for 7 days. To finish the work in that window, continue the intent from your coding agent with tiden intent continue. After a checkpoint merge, continue the successor:

tiden intent continue --intent intent/checkout-refactor-cont

tiden intent continue on an intent that already merged does not write to it. It tells you to run tiden intent reopen "<objective>", or to continue the successor when a checkpoint merge created one.

To stop Tiden from merging intent branches for a whole product, see Automatic intent merge.

Edit a branch's description

Change the description in place when it is out of date, for example after someone answers an open question that the description names:

tiden branch update \
  --product-id <product-id> \
  --name intent/checkout-refactor \
  --description "Checkout specs. The owner confirmed the coupon limit."

For a long description, use --description-file <path>, or --description-file - to read it from standard input. --description "" clears the description.

The branch keeps its ID, specs, links, review, and run history. You can edit the description of an open, merged, or closed branch. Do not delete and re-create a branch to change its description: that loses its links and history.

Close a branch

Close a branch when its changes will not be merged but you want to keep its specs, links, review, and run history:

tiden branch close --product-id <product-id> --name intent/checkout-refactor

In the web app, open the Branches page, open the row menu of the branch, and select Close. You can also select Close in the header of the branch page. Tiden asks you to confirm.

The branch then shows under the Closed filter, and the branch page says who closed it and when. It takes no new changes and is not reopened; to continue the work, start a new intent. Closing a branch that is already closed changes nothing, so the command is safe to repeat. You cannot close main, a merged branch, or an automatic branch that Tiden created from a pull request.

What a closed branch keeps, what it refuses, and the API error codes are in Closed branches.

Delete

Delete a branch only when you want to discard its changes:

tiden branch delete --product-id <product-id> --name intent/checkout-refactor

Deleting a branch discards unmerged branch-local changes. Its links and history go with it. To end a branch and keep its specs, links, review, and run history, close it instead.