# Agent session, terminal tab, branch, or worktree: what is the difference?

> A practical map of the four things people mix up when running multiple coding agents, with a two-agent example and checkout verification commands.

Canonical HTML: https://canopyide.dev/guides/agent-session-vs-tab-vs-worktree
Article date: 2026-09-28

Two agent tabs do not automatically mean two isolated copies of your code. A tab is where you look; a CLI session holds one conversation; a Git branch names a line of work; a worktree is a checked-out directory. Know which one you created before letting two agents edit at once.

## Four objects, four jobs

A terminal tab is a view into a running shell or agent process. An agent session is the CLI's conversation and tool history; its resume behavior belongs to that CLI. A branch points at commits in Git, but two processes in one working directory still see the same uncommitted files. A worktree gives one repository another checked-out directory and separate working-tree state. Git documents that one repository can have a main worktree and additional linked worktrees. Canopy's current-main README says it can launch supported CLIs in the current checkout or an isolated worktree and show branch and session context together; verify the installed release and CLI's resume support.

*What each thing separates in a two-agent task.*

| Object | Separates | Does not separate by itself |
| --- | --- | --- |
| Terminal tab | What you see and type into | Files, branch, provider account |
| Agent session | Conversation and tool history in one CLI | Checkout or other agents' edits |
| Git branch | Committed history and proposed change | Two agents editing one directory |
| Git worktree | Checked-out files and uncommitted state | Shared services, ports, credentials, or review ownership |

## Try a two-agent assignment

Suppose one agent is changing the settings page and another is reviewing API error handling. Put the code-changing task on branch `settings-form` in its own worktree, and the API task on branch `api-errors` in another. Give each its own agent session and terminal. If the API job is only a read-only investigation, it may share a checkout if nobody changes the files it reads, but record which commit it studied. In either case, name the outcome and owner. More tabs on one checkout can be useful for a shell and a single agent; they do not prevent simultaneous writes to the same file.

## Verify the directory instead of trusting the tab label

From each agent terminal, ask for `pwd`, `git status --short --branch`, and `git worktree list`. Compare the printed directory and branch with the assignment. `git worktree list` shows the registered checkouts; `git status` shows changes in the current one. Do this before a code edit or when a resumed session seems to be on the wrong task. If the commands show one shared directory, pause one code-changing agent and move it to a separate checkout before continuing. Never use a branch name alone as proof of file isolation.

## Remember the things worktrees still share

Separate checkouts can still connect to the same database or fight for the same local port. Ignored `.env` files and installed dependencies may differ by directory. Assign ports, inspect Canopy's Servers output, and verify which URL belongs to which checkout. The worktree environment and port-collision guides linked below walk through these failures. Provider logins also remain with each installed CLI profile; a worktree is not a new model account or a billing boundary.

## Finish at the change, not the session count

When both agents finish, inspect each branch's diff and tests, then integrate deliberately. A stopped tab does not mean its branch was merged, and a resumed conversation may refer to files that changed after the earlier turn. Canopy's Agent Workspace can join session, checkout, commits, diff, and PR according to the app README; use that evidence to decide what is complete. Keep the branch, current test result, and next action in a short handoff so a new session can continue without treating an old transcript as current source truth.

## Copyable resources

### Two-agent assignment card

Copy one card for each independently changing agent.

````text
Outcome: [one testable result]
CLI and agent session: [name / session identifier if available]
Worktree path: [absolute or project-relative directory]
Branch: [branch name]
Run command and port: [command / local URL]
Files or area owned: [scope]
Acceptance check: [what I will inspect]
Integration owner: [person or session]
Before editing: compare pwd, git status --short --branch, and git worktree list.
````

## Frequently asked questions

### Can two coding agents use the same branch in separate tabs?

They can, but if both tabs use one checkout they share uncommitted files and can overwrite or confuse each other's work. Use separate worktrees and branches for independent code changes, then integrate them.

### Does a new worktree copy my agent conversation?

No. A worktree separates checked-out files. Conversation history and resume are features of the installed CLI and its session store.

### Is a Git branch enough to isolate two agents?

A branch identifies commit history. Two agents in one directory still see and edit the same working files. Confirm distinct worktree paths when both will modify code.

### Does a worktree give each agent its own dev server?

No. Start and configure services for each checkout, assign distinct ports where needed, and verify the URL and backing API or database.

## Sources and further reading

- [Git: linked worktree definition and commands](https://git-scm.com/docs/git-worktree)
- [Canopy app README: agent launch, worktrees, and Agent Workspace](https://github.com/FluidWorksApp/canopy-ide/blob/main/README.md)
- [Canopy agent integration parity audit](https://github.com/FluidWorksApp/canopy-ide/blob/main/docs/agent-parity.md)

## Related Canopy pages

- [How to run multiple coding agents without losing track](https://canopyide.dev/guides/run-multiple-coding-agents.md)
- [Git worktrees for parallel coding agents: commands and cleanup](https://canopyide.dev/guides/git-worktrees-for-parallel-coding-agents.md)
- [How do I stop two agent worktrees from using the same port?](https://canopyide.dev/use-cases/avoid-dev-server-port-collisions-with-worktrees.md)
- [Find the old agent session, then resume the right project](https://canopyide.dev/use-cases/find-old-agent-session-and-resume-project.md)
- [Canopy vs Claude Code Desktop: which agent workspace fits?](https://canopyide.dev/use-cases/canopy-vs-claude-code-desktop.md)

Canopy runs installed coding CLIs; CLI accounts, model selection, and provider billing remain separate. Check the installed release before relying on version-specific behavior.