Branches

A branch is the primary unit of work in Agor. It’s an isolated git working directory — a checkout of your repo at a specific branch — paired with a metadata record (issue/PR links, owners, environment, sessions) that gives it identity on the board.

Best practice: 1 branch = 1 issue = 1 PR = 1 feature.

Agor uses git branches under the hood, so multiple branches of the same repo can be checked out simultaneously without stashing or switching. Agor manages all of that for you — just create a branch in the UI or CLI and it handles the git plumbing.

~/.agor/worktrees/<repo>/<name>
├─ feature/oauth2-auth     ← branch checked out here
├─ Sessions: Claude #1, Codex #2 (review fork)
├─ Issue:  github.com/me/repo/issues/123
└─ PR:     github.com/me/repo/pull/456

Left: a branch’s static anatomy — branch, PR, env, files, sessions in one tile. Right: the same primitive packed with a coordinator and eight running children.

Why a workspace, not just a git branch

A git branch is a ref. An Agor branch is a workspace.

• Parallel work — Run 5 features in 5 branches simultaneously. No git stash, no “kill your dev server so I can test mine.”
• Spatial identity — Each branch is a card on a board. You can see, drag, group, and zone them.
• Session containers — Every session belongs to exactly one branch. The conversation tree lives on the card.
• Environment scope — Dev servers, ports, and processes are scoped to the branch, not the repo.

Each branch is fully isolated — changes in one don’t affect another. AI agents can work on three features in parallel without stepping on each other’s filesystem.

Anatomy

A branch is a filesystem directory plus a database record. The record tracks:

Behind every card: the branch details modal — General / Sessions / Environment / Files / Schedule tabs. The same fields the table above describes, rendered as actual inputs.

Sessions, tasks, comments, and artifacts all reference a branch. The branch is the spine.

GitHub-native workflow

Because each branch carries issue_url and pull_request_url, AI agents have unambiguous context for what they’re working on. Zones can use that context directly:

deeply analyze this github issue: {{ branch.issue_url }}

When the agent runs, it sees the link, fetches the issue, and works against the right branch. No copy-paste, no “which ticket was this for again?”

Environments

Each branch can have its own dev environment — long-running processes (dev server, database, watchers) scoped to that branch, with auto-assigned unique ports so multiple branches can run simultaneously without collisions.

Configure once on the repo, then everyone on your team gets one-click start/stop on every branch.

# Per-repo template, ports derived from branch's unique_id
up_command: 'PORT={{add 9000 branch.unique_id}} pnpm dev'
down_command: "pkill -f 'vite.*{{add 9000 branch.unique_id}}'"
app_url_template: 'http://localhost:{{add 9000 branch.unique_id}}'

→ Environments guide for the full setup.

Archival

When a feature ships and the PR merges, you usually want to clean up disk without losing the conversation history, analytics, or issue/PR linkage.

Filesystem options:

• Leave untouched — Metadata-only archival. Files stay on disk.
• Clean workspace — Runs git clean -fdx (removes node_modules, builds, untracked files).
• Delete completely — Removes the branch directory from disk.

Metadata options:

• Archive (recommended) — Hides from board, preserves all sessions and conversations for analytics and history.
• Delete permanently — Removes all data including sessions and conversations. No undo.

Best practice: Archive with filesystem cleanup after PR merge. Only delete permanently for experimental branches with no valuable data.

Branch-level features

The branch is also where several other features attach:

• Sessions & Trees — Every session lives in exactly one branch. The fork/spawn tree appears on the branch card.
• Boards & Zones — Branches are placed on boards; dropping into zones triggers templated prompts.
• Multiplayer & Social — Spatial comments pin to branches; shared terminal sessions are branch-scoped.
• Scheduler — Templated prompts can fire on a schedule against a specific branch (great for assistant heartbeats).

Permissions (RBAC)

When execution.branch_rbac: true is set, branches enforce ownership and a per-tier others_can permission:

See Security for deployment modes and the trust boundary discussion.

Related

• Sessions & Trees — Conversations and genealogy that live inside a branch
• Boards & Zones — How branches are organized spatially
• Environments — Per-branch dev environments
• Scheduler — Time-based prompts targeting branches