Docs Concepts

Parallel work

Several agents can work at once: each can get its own git worktree, overlaps are flagged before they collide, and real clashes become a suggested ticket. Teamtrail never merges, pushes or deletes branches.

#A workspace per task

Turn it on in workspaces.json (or Settings → Workspaces), or let an agent ask for one with claim_ticket workspace: true. Claiming then creates:

  • a branch teamtrail/<trail>/<n> from the current HEAD;
  • a worktree at <repo parent>/<repo>.teamtrail/<trail>-<n> by default.

The claim result returns workspace: { path, branch, base }, and the agent edits and commits only there. Claiming again reuses the same worktree. Checks, git evidence and the claim baseline for that ticket run in the worktree. When the ticket completes, the result and a ticket comment name the branch for you to review and merge.

Outside a git repo, or in a repo with no commits, the claim still succeeds and the result explains why there's no workspace (workspaceNote).

Removing a finished workspace: in Settings → Workspaces (which lists every worktree as active or finished) or on a closed ticket in the inspector, choose Remove workspace. It runs git worktree remove and keeps the branch. It refuses while the ticket is still claimed and never touches your main checkout; if the worktree has uncommitted changes it asks first. Over HTTP: POST /workspaces/remove { mapId, ticketId, force? }.

#Overlap warnings

An agent can declare the files it expects to change with claim_ticket touches (path globs, up to 50). If another live claim declared overlapping files, the claim result has a warnings entry naming the other ticket, agent and paths, and an overlap item appears in Waiting on you.

Overlap errs on the side of warning:

  • two plain paths overlap when they're equal;
  • a plain path overlaps a glob that matches it;
  • two globs overlap when one's fixed prefix lies inside the other's (src/** and src/app/*.ts).

The ticket inspector shows the declared files and the branch. To hold one of the claims, open it and use Release to queue.

#Integration check

Every 10 seconds ($TEAMTRAIL_INTEGRATION_POLL_MS), Teamtrail compares git diff --name-only <base>...<branch> across active claims that have worktrees. When two branches changed the same files, an integration item lists them with Add integration ticket: a task titled "Bring together #a and #b", blocked by both tickets, listing the files. Nothing is created or merged automatically. Only active claims are compared; once a ticket closes, its branch drops out.

From the chat, status includes a parallel summary (workspaces, declared overlaps, changed-file clashes) when there's anything to report.