# What do file claims solve when coding agents share a repository?

> Use visible file ownership to catch overlapping plans early, then verify checkout isolation, actual edits, and the final integrated diff.

Canonical HTML: https://canopyide.dev/use-cases/file-claims-for-parallel-coding-agents
Article date: 2026-09-28

Two agents can agree to work on different features and still reach for the same configuration or component file. Canopy's product page shows file claims so overlapping work is visible early. A claim is a coordination signal; the real editing boundary is the checkout, and the final truth is the diff and running behavior.

## Name the work before assigning files

Start with two outcomes, not two lists of filenames. For a checkout flow, Agent A might own the declined-card UI state while Agent B investigates a payment API timeout without editing. The shared API contract and final acceptance checks need one human owner. A file claim is useful when the task starts to touch checkout.ts or a shared test fixture: the owner can see that a second session may be entering its area. It does not decide whether two proposed behaviors are compatible. A short task brief should still name the intended branch, read-only or edit authority, and stop point.

## Separate a claim from a worktree

Canopy's public page describes agents claiming files so overlapping edits are visible before they happen. Git worktrees solve a different problem: each linked worktree is its own working directory and branch, so uncommitted files in one checkout do not overwrite the other's working files. A claim may draw attention to overlap in one shared checkout; do not treat the visual claim as proof of an operating-system lock or a guarantee that a CLI will refuse to write. Conversely, two agents in separate worktrees can both change the same source path and create a merge or design conflict later. Check the installed Canopy release and run a disposable trial before relying on the claim display for a real team process.

*Four different signals in one parallel-agent task.*

| Signal | Answers | Still requires |
| --- | --- | --- |
| Task owner | Who should decide the behavior? | Written acceptance and escalation rule |
| File claim | Which session has declared or surfaced work on this path? | Verify delivery, freshness, and actual edits |
| Worktree and branch | Where can uncommitted changes live independently? | Check current directory and integration |
| Git diff and PR | What code actually changed? | Review combined behavior and tests |

## Pause when the overlap is meaningful

Suppose Agent A claims the checkout component while Agent B's investigation reveals the same component must change to handle timeout retries. Do not let both agents continue writing the shared checkout while you guess which patch will survive. Ask Agent B for a read-only finding with the failing path and expected behavior. Give one implementer authority over the change or give each a separate branch with a named integration owner. If both branches already changed the file, compare intent before resolving line conflicts. The merge-conflict guide covers the recovery path; a green merge command alone does not prove both behaviors survived.

## Verify claims against the current state

In the installed app, start two supported CLI sessions on a disposable repository. Give each a distinct task, then have both identify a harmless shared file they might need. Observe whether Canopy shows the claim, which session it attributes it to, and whether the other session sees an overlap warning. Record versions and the exact checkout of each terminal. Then inspect Git status and the latest diff in every worktree. CLI hooks and file attribution differ by integration, so a missing or stale claim should prompt inspection, not an assumption that no one touched the file. Do not intentionally race writes to important code just to test the UI.

## Finish with one integration decision

When work stops, release or clear any claim through the controls in the installed release, and verify no active agent still owns a pending edit. Compare each branch with the acceptance criteria, merge through the normal PR flow, and run the combined success and failure paths. Record which agent contributed what and which person accepted the result. A file claim is valuable when it prevents an unnoticed overlap early; it is not a substitute for isolated checkouts, final diff review, or a decision about the shared design.

## Copyable resources

### Two-agent overlap card

Use before assigning the second edit and after any claim conflict appears.

````text
Shared outcome and acceptance checks: [ ]
Agent A task, checkout, branch, and allowed edit area: [ ]
Agent B task, checkout, branch, and read-only/edit scope: [ ]
Shared files or contract likely to be touched: [ ]
Canopy claim observed, by whom, and at what time: [ ]
Actual git status/diff in each checkout: [ ]
Overlap decision and single integration owner: [ ]
Final combined tests, preview behavior, and PR decision: [ ]
````

## Frequently asked questions

### Does a Canopy file claim lock a file against another agent?

Do not assume it does. The public product description promises visibility of overlapping work; test the installed release and use separate worktrees for file isolation.

### Why use file claims if agents have separate worktrees?

Separate worktrees protect uncommitted files from overwriting one another, but agents can still make incompatible changes to the same source path or API contract. Claims can surface that coordination need early.

### What if a claim is missing but Git shows an edit?

Treat Git and the working tree as the authority for actual changes. CLI integration and attribution can differ; inspect the session, checkout, and latest diff before assigning ownership.

## Sources and further reading

- [Canopy product page: agent messages and file claims](https://canopyide.dev/)
- [Canopy agent integration parity audit](https://github.com/FluidWorksApp/canopy-ide/blob/main/docs/agent-parity.md)
- [Official Git worktree documentation](https://git-scm.com/docs/git-worktree)
- [Public discussion about multi-agent edits in one repository](https://www.reddit.com/r/ClaudeCode/comments/1w3nw2j/multi_agents_in_the_repo_race_conditions/)

## Related Canopy pages

- [How to run multiple coding agents without losing track](https://canopyide.dev/guides/run-multiple-coding-agents.md)
- [Agent session, terminal tab, branch, or worktree: what is the difference?](https://canopyide.dev/guides/agent-session-vs-tab-vs-worktree.md)
- [Git worktrees for parallel coding agents: commands and cleanup](https://canopyide.dev/guides/git-worktrees-for-parallel-coding-agents.md)
- [My coding agent edited the wrong branch or worktree. What now?](https://canopyide.dev/guides/coding-agent-edited-wrong-branch-or-worktree.md)
- [How do I resolve a merge conflict between two coding agents?](https://canopyide.dev/guides/resolve-merge-conflict-between-coding-agents.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.