Create Worktree

Register a git worktree for a session. Call after git worktree add.

eb2e44f8 — when the caller also supplies base_sha + base_branch, this additionally persists an IMMUTABLE base manifest for the worktree (repo identity, base branch, base SHA, owning sprint item), returned under the manifest key. That manifest is what meridian.worktree_merge_guard.validate_worktree_merge checks against later, before a merge/completion is allowed to proceed. Omitting base_sha/base_branch skips manifest creation entirely — backward compatible with callers that only register session/branch/path; no retroactive validation is imposed on worktrees that never opted in.

post/projects/{project_id}/worktrees

Request

  • Base URL: https://usemeridian.us (the document declares no server; this is the origin it was published from)
  • URL: https://usemeridian.us/projects/{project_id}/worktrees
  • Auth: none declared

Path parameters

project_idstring required

Request body

session_idstring required

Session that owns this worktree.

branchstring required

Git branch name, e.g. worktree/abc12345.

pathstring required

Filesystem path of the worktree.

item_idstring nullable

Sprint item this worktree was created for.

pidinteger nullable

eb2e44f8 — OS PID of the process that created this worktree. Used by the cleanup guard to confirm no live process is still using the directory before it is removed from disk.

base_shastring nullable

eb2e44f8 — commit SHA the worktree was branched from. Supplying this together with base_branch persists an IMMUTABLE base manifest for the worktree, later checked before merge/completion is allowed to proceed. Omitting it skips manifest creation entirely (backward compatible).

base_branchstring nullable

eb2e44f8 — branch the worktree was branched from, e.g. 'dev'.

repo_identitystring nullable

eb2e44f8 — stable identity for the repo this worktree belongs to (e.g. a remote URL or repo name). Free-form; recorded on the base manifest for audit purposes only, never validated against disk. Defaults to project_id when omitted.

Response

Successful Response

object required

Changes