Detect coworker Claude agents in a shared checkout. Use when starting a session in a shared clone, before destructive git ops (stash, reset, checkout), or before bulk-edit / commit-loop workflows.
Detect coworker Claude agents in a shared checkout. Use when starting a session in a shared clone, before destructive git ops (stash, reset, checkout), or before bulk-edit / commit-loop workflows.
See .claude/rules/agent-coworker-detection.md for the full rationale and
signal design.
Bulk-edit / commit-loop precondition
Bulk-edit and commit-loop workflows (git-commit-workflow "Bulk-edit / per-plugin commit loops", per-package release-please loops, mass refactors) MUST run this check up front, before staging any files — not opportunistically partway through.
Why front-loaded, not opportunistic. A real divergence scenario from the field: two Claude sessions converged on the same trim-descriptions task. Session A used general-purpose subagents in the main checkout; session B used worktrees + per-plugin commits. Session B landed 11 clean per-plugin commits and stopped. Session A's first commit then grabbed all 30 remaining plugins in a single mega-commit, because session A had previously hit a git commit -a failure that left everything pre-staged, and session B's loop never noticed because it ran /git:coworker-checkduring its work rather than before. The end result was correct, but the commit history said docs(configure-plugin): ... for changes spanning 30 plugins.
The rule: the orchestrator stops before fan-out if the playing field is contended. Mid-loop checks let "the agent who happens to look first wins" — which is non-deterministic and produces misleading commit histories.
Verdict from up-front check
What to do
clear
Proceed with the bulk-edit / commit loop
drift_detected
Inspect the new files. If they are yours from earlier in the session, proceed with explicit paths. If unknown, stop and ask.
worktree_leak_suspected
A child worktree-isolated agent is leaking an untracked file into the parent (issue #1319). Do not stage or stash the matching path. Wait for the child's commit, then re-run the check before continuing.
bare_flip_suspected
The shared checkout was flipped to core.bare=true, or a leaked GIT_DIR / GIT_WORK_TREE env points away from the repo (issue #1692). Stop and recover before any further git ops — see the Recovery section. Do not start the loop.
coworker_detected
Stop. Recommend git worktree add ../<repo>-<task> for a fresh isolated checkout, or wait for the other session to finish. Do not start the loop.
Worked example: detection enables defensive restoration (#1277)
A second positive scenario from the field — the "stop and inspect" rather than "stop and abort" branch. A description-trimming refactor agent ran in a checkout that already had ~7 active claude processes touching the same files. The coworker_detected verdict fired off the process-scan signal alone (the ps-based fallback, well before any taskwarrior coordination existed for this batch). Per the verdict-to-action table above, the agent did not stash or reset; it scoped its pass to the remaining 17 files and inspected the coworker's already-landed edits before writing.
That inspection caught a real regression: in git-fork-workflow, the coworker had cut the description from 358 → 240 chars and dropped the sibling cross-reference For creating upstream PRs, see git-upstream-pr. The agent re-added the line on its own pass. Eight other skills had a stale modified: date for the same reason and were stamped forward. No work was lost; a silent cross-reference regression became an explicit recovery. Evidence: issue #1277.
Context
Repo root: !git rev-parse --show-toplevel
Git dir: !git rev-parse --git-dir
Current status: !git status --porcelain=v2 --branch
Report the three file paths printed. These are the marker and baseline files — do not commit or delete them. They live inside .git/ and are not tracked.
Look up the current session's baseline files (if --claim was run earlier this session). Then run detection. Pass --self-agent claude-${CLAUDE_SESSION_ID:0:8} so taskwarrior claims by this same session are reported as OWN_CLAIM_* rather than counted as coworkers:
If no --claim was run, omit the --baseline-* flags — drift detection will return unknown but marker, process, and taskwarrior signals still work.
The taskwarrior signal is best-effort: when task or jq is not on PATH, the script reports TW_SCAN_METHOD=unavailable and the verdict falls back to the three git-side signals.
Step 4: Interpret the verdict
Parse the VERDICT= line from the script's output:
Verdict
Meaning
Action
clear
No coworker detected
Proceed; still prefer explicit git add <paths> over git add -A
drift_detected
Files appeared since baseline but no other process/marker/claim found
Inspect NEW_STATUS_LINES — may be coworker or may be a forgotten earlier edit. Ask the user before stashing.
worktree_leak_suspected
Untracked file in parent matches a path held by a linked worktree (issue #1319)
Do not stash or commit the matching path. Wait for the child worktree's commit to reclaim it. Avoid committing on the parent branch until child agents are done.
bare_flip_suspected
CORE_BARE=true on a shared working checkout, or a LEAKED_GIT_DIR / LEAKED_GIT_WORK_TREE env points away from the repo (issue #1692)
Stop and recover. Flip core.bare back to false and/or unset the leaked env before any further git ops — see the Recovery section below. Recover any wiped untracked work from the reflog / agent worktree branches.
coworker_detected
Another agent/process/taskwarrior claim is active in this clone
Do not stash, restore, or reset. Report the MARKER_PID / PROC_PID / TW_CLAIM_* entries. Recommend the user switch to a worktree.
The six signals are independent — any one of MARKER_COUNT > 0, PROC_COUNT > 0, or TW_CLAIM_COUNT > 0 raises coworker_detected. A non-zero WORKTREE_LEAK_COUNT on its own raises worktree_leak_suspected, and a non-zero BARE_FLIP_COUNT raises bare_flip_suspected (ranked first, since a bare flip breaks git for every linked worktree). OWN_CLAIM_* lines are this session's own taskwarrior claims and do not contribute to the count.
Step 5: Report findings
Print a short summary:
Verdict
Count of markers + processes + drift entries
If non-clear, the specific PIDs or changed files
Recommended next action (worktree, ask user, proceed with explicit paths)
Post-actions
On drift_detected or coworker_detected: do not run git stash, git reset --hard, git checkout -- ., or git clean in this session. Stage only explicit paths.
Suggest the user run git worktree add ../$(basename $(git rev-parse --show-toplevel))-<task> for a clean isolated checkout.
Integration
Other git-plugin skills should invoke this via SlashCommand before destructive operations or fan-out:
Before staging (or before starting a per-plugin commit loop):
Use SlashCommand to invoke `/git:coworker-check`.
If the verdict is not `clear`, stop and ask the user how to proceed.
Bulk-edit / commit-loop skills (git-commit-workflow, per-plugin release-please loops, mass refactors) must invoke this before staging any files — see the "Bulk-edit / commit-loop precondition" section above for why an opportunistic mid-loop check is insufficient.
Hook-based enforcement (blocking git stash / git reset --hard when a coworker is detected) belongs in hooks-plugin, not here.
Add --baseline-status + --baseline-stash from a --claim run
One-line verdict check
... | awk -F= '/^VERDICT=/ {print $2}'
Recovery
Detection prevents corruption. When prevention fails — a coworker
session moved HEAD between your steps, your commit landed on the
wrong branch, your branch accumulated commits you didn't make — see
REFERENCE.md for procedural recovery.
Always run git reflog -20 first. The reflog is the ground truth
for every HEAD move and ref update during the collision window —
recovery procedures all begin from a clear reflog read.
Recovering from a bare flip / leaked GIT_DIR (issue #1692)
When detection returns bare_flip_suspected, the shared checkout was
flipped to core.bare=true (or a GIT_DIR / GIT_WORK_TREE env was
leaked) by a concurrent agent fleet. Recover before any further git ops:
Flip core.bare back to false so the working tree is usable again:
git config core.bare false
If even git config refuses, drive it explicitly with the recovery
override the issue used (note -c core.bare=false plus an explicit
GIT_DIR/GIT_WORK_TREE):
GIT_DIR=.git GIT_WORK_TREE=. git -c core.bare=false status
Unset any leaked env reported as LEAKED_GIT_DIR /
LEAKED_GIT_WORK_TREE so git stops targeting another tree:
unset GIT_DIR GIT_WORK_TREE
Recover wiped untracked work. A concurrent branch switch / reset
can silently delete uncommitted, untracked files. Untracked files
are not in the reflog, so check first for any copy a sibling agent
committed — git fsck --unreachable and the agent worktree branches
are the best source:
git reflog -20
git fsck --unreachable
git worktree list
git branch -a
A file an agent worktree committed survives on its branch even when
the parent's untracked copy was wiped. If no committed copy exists,
the work is unrecoverable — which is why committing early matters.
Commit early to minimize untracked-file exposure
Untracked files are the only work a concurrent branch switch/reset can
destroy with no recovery path (committed work survives in the reflog;
untracked work does not). When many sibling worktrees are active in one
clone — high LINKED_WORKTREE_COUNT, or a coworker_detected /
bare_flip_suspected verdict — commit or stash new files promptly
rather than leaving them untracked, and prefer working in your own
git worktree add ../<repo>-<task> so a flip in the shared checkout
cannot reach your tree.
Related Skills
/git:maintain — invokes this before any stash/clean operation
/git:commit — invokes this before staging when working in a shared checkout
git-commit-workflow — invokes this as a precondition for bulk-edit / per-plugin commit loops
git-branch-pr-workflow — recommends worktrees as the structural fix
/taskwarrior:task-claim — sister signal; writes the +ACTIVE claim that this skill now reads
/taskwarrior:task-release — drops the claim that contributes to TW_CLAIM_COUNT
