# CLI Collaboration > Use when multiple CLI agents or assistants alternate on the same repository or explicit shared handoff workflow — especially with AGENT_HANDOFF.md, side-by-side AGENTS.md/CLAUDE.md/GEMINI.md, dirty worktrees, ownership notes, red tests, resume/continue requests, or /cli-collaboration in Grok Build. - Skill: `spe1977/cli-collaboration` (Agent Skill, multi-file: 29 files) - Install (CLI): `npx skillmds@latest add spe1977/cli-collaboration` - Raw SKILL.md: https://api.skillmd.com/api/skills/spe1977/cli-collaboration/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: Spe1977 (https://skillmd.com/u/spe1977) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/spe1977/cli-collaboration --- # CLI Collaboration Use a written handoff as the source of truth when CLI agents, or one agent across sessions, work in the same project. The goal is continuity without destroying state left by the user or another agent. ## Core Rule Read `AGENT_HANDOFF.md` before interpreting `git status`. Never infer ownership from a dirty worktree alone. If collaboration is paused via `.cli-collaboration-off` or `Status: paused` in the handoff, still preserve existing work and ask before touching shared files. ## Language Preference Run this once, as the final step of the activation cycle, so the whole session (and every later activation, by any agent) speaks the user's chosen language. The preference lives in one global file: `${XDG_CONFIG_HOME:-$HOME/.config}/cli-collaboration/config.json`. 1. Run `scripts/lang.sh get` from the installed skill directory. 2. **If it prints a value (exit 0):** continue the session in that language. Do not ask again. 3. **If it exits non-zero (not configured):** ask the user, in English: `Choose your language:` — then run `scripts/lang.sh set "" --by ` and continue in that language from then on. The script never prompts on its own — in a CLI-LLM session there is no TTY, so **you** (the LLM) mediate the prompt in chat. To change the language later, the user runs `scripts/lang.sh set "" --force`. Non-interactive runs (CI) use `scripts/lang.sh ensure-noninteractive`, which reads `CLI_COLLAB_LANG` or falls back to `en`. > **Scope note:** this honors the language at each skill activation, not in > every unrelated conversation. Projecting the preference into each agent's > native memory (`CLAUDE.md`/`GEMINI.md`/`AGENTS.md`) is a deferred Phase 2. ## Start Gate Before editing, state: ```text Handoff read: Current task: Files I will touch: Expected red test: Reserved zones confirmed: Stop condition: ``` If you cannot fill a field, read more or ask. Do not improvise. ## Bootstrap Without Handoff If no handoff exists, create or propose `AGENT_HANDOFF.md` before normal work. Include the user's request, current path, `git status --short --branch` if available, declared ownership, and the next concrete action. Mark it as bootstrap state, not authoritative history. If `AGENT_HANDOFF.md` is missing but a known workflow seed file such as `brainstorming.md` exists in the same folder, read that seed file before creating a generic handoff. Follow its bootstrap instructions to create the initial `AGENT_HANDOFF.md`. For alternate workflows such as multi-LLM brainstorming, load `references/alternate-workflows.md` only when the user explicitly asks for that workflow, the handoff declares it, or a known seed file declares it. ## Ownership Use this exact line shape: ```text - : — ``` Patterns are bash `case` patterns: `*` matches any sequence of characters **including `/`**, so `scripts/*` matches both `scripts/foo.sh` and `scripts/sub/foo.sh`. Use explicit path segments when you need to scope to a single directory level. `**` is not a recognized token. Sections: - `### agent-owned`: files assigned to Codex, Claude, Gemini, Grok, or another named agent. Globs are allowed. Parenthetical notes like `(pending Phase 2)` are advisory. - `### user-reserved`: user-owned files. Stop before editing. - `### frozen`: published or protected files. Stop before editing. Run `scripts/check-ownership.sh --agent ` when the file list intersects handoff ownership or before risky edits. Exit `0` means no conflict detected, `1` means ownership conflict, `2` means malformed handoff or usage error. ## Conflict Handling When a file is owned by someone else, user-reserved, frozen, or unexpectedly changed: 1. Stop before editing. 2. Name the file, owner, and risk. 3. Offer reassignment, deferment, or a smaller scope. 4. Wait for the user or owning agent to decide. Do not resolve ownership conflicts by overwriting, reverting, stashing, or cleaning. ## Work Discipline - Keep edits inside declared files. - If a new file becomes necessary, announce it before editing. - Use tests for implementation work when possible. A failing test is a good handoff artifact. - Prefer a small complete task plus precise handoff over a broad half-finished refactor. - The single-agent case still uses the handoff: it is project memory between sessions. - Only one parent session updates `AGENT_HANDOFF.md`; parallel subagents report back instead of editing it concurrently. ## User Supersession The user's latest instruction wins. If it changes scope mid-turn, write a brief supersession note in the final handoff and adjust the declared file list before editing new files. ## Destructive Actions Never run or recommend these without explicit user approval: - `git reset --hard` - `git clean` - `git stash` - `git restore` - `git checkout --` - lateral overwrite of files you did not author ## Adapters Load adapter notes only when relevant: - `references/codex-adapter.md`: Codex install paths, AGENTS.md, and script usage. - `references/claude-adapter.md`: Claude Code hooks and command guidance. - `references/gemini-adapter.md`: Gemini activation and GEMINI.md guidance. - `references/grok-adapter.md`: Grok Build discovery, tools, Bluefin paths, and agent identity. ## End Of Shift Update `AGENT_HANDOFF.md` last with: ```text Agent: Date/time: Task: Status: Files changed: Tests red: Tests green: Open concerns: Next agent starts from: Do not touch: ``` Keep recent history useful: preserve the last three detailed handoff blocks and summarize older entries if the file gets large.