/git:coworker-check

Detect another agent working in the same repo clone and warn before destructive operations that could destroy its uncommitted changes.

When to Use This Skill

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-check during 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.

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
• Stash count: !git stash list
• Existing markers: !find . -path './.git/.claude-session-*' -maxdepth 3

Parameters

Parse $ARGUMENTS for the mode flag. Default is --check.

Execution

Execute this detection workflow:

Step 1: Resolve mode

Inspect $ARGUMENTS. If it contains --claim, go to Step 2a. If it contains --release, go to Step 2b. Otherwise (including empty), go to Step 3.

Step 2a: Claim (write marker + baseline)

Run:

bash ${CLAUDE_SKILL_DIR}/scripts/claim-session.sh --project-dir "$(pwd)"

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.

Stop here.

Step 2b: Release (remove marker + baseline)

Run:

bash ${CLAUDE_SKILL_DIR}/scripts/release-session.sh --project-dir "$(pwd)"

No output is expected. Stop here.

Step 3: Detect coworkers

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:

bash ${CLAUDE_SKILL_DIR}/scripts/detect-coworkers.sh \
  --project-dir "$(pwd)" \
  --self-agent claude-${CLAUDE_SESSION_ID:0:8} \
  --baseline-status .git/.claude-baseline-$$.status \
  --baseline-stash .git/.claude-baseline-$$.stash

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:

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:

1. Verdict
2. Count of markers + processes + drift entries
3. If non-clear, the specific PIDs or changed files
4. 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.

Agentic Optimizations

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.

Quick triage:

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:

1. 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
   

2. 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
   

3. 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