How to Share Your Claude Code Project With a Teammate

Hello builders,

A teammate can clone your repository in the middle of a project, start Claude Code, and have their agent name the plan you’re working on without a single call. Leave that to chance and a fresh agent decides for itself from whatever it finds, and one builder who counted across 14 of their own repositories, in a Reddit thread on multi-agent workflows, found a 126KB handoff document, 51 days old, that every new agent was still reading as current. People search for how to share a Claude Code session with a teammate, and what we end up sharing is one small file that says what’s current, plus a hook that stops work when that file is wrong.

The request to share the session itself has been filed more than once, and issue #48828 on the Claude Code repository states the problem well.

Currently, each user must start a separate session with no shared context, leading to duplicated effort and context loss when handing off work.

That issue was closed as a duplicate of #40981, which was closed as a duplicate of #10368, which was closed as not planned. So what can a teammate actually get from us? A session stays with one person on one machine, so whatever they need out of ours has to live somewhere they can clone. Git already gives us a shared history and says nothing about what’s being worked on right now, which is the part a new agent gets wrong.

One file that says what’s current

We make a workspace/ folder in the repository and put index.md in it. The status goes in the first column and exactly one row is ACTIVE:

# Workspace index

Read this before doing anything. Exactly one plan is ACTIVE.
If you cannot tell what to work on from this file, stop and ask.

## Plans

| status | plan | owner |
|---|---|---|
| ACTIVE | plans/002-auth-migration.md | jc |
| DONE | plans/001-config-loader.md | sam |

Finished plans stay in the file, because an agent that can see 001-config-loader.md was done last week won’t propose doing it again. I keep the status here because a fresh session walks the files in front of it, and an issue tracker isn’t one of them. To make sure it reads this one first, we add a pointer at the top of CLAUDE.md:

## Before doing anything

Read `workspace/index.md`. Exactly one plan is ACTIVE; work only on that plan.

I tried it on Claude Code v2.1.292 with a fresh session and one question, “What should I be working on in this repository right now?”, and it answered with plan 002 and what the plan was for. Your teammate pulls and gets the same answer, because the index is a file and files cross machines the way they always have.

The check that stops a second plan

A file like this goes stale the day two people each mark their own plan ACTIVE. So we save a short script as workspace/bin/check-index.sh and run chmod +x on it.

#!/usr/bin/env bash
# Refuses unless the workspace has exactly one ACTIVE plan.
# Exit 2 blocks. Any other non-zero code does NOT.
set -uo pipefail

INDEX="${WORKSPACE_INDEX:-workspace/index.md}"

if [[ ! -f "$INDEX" ]]; then
  echo "check-index: no index at $INDEX" >&2
  exit 2
fi

active=$(grep -n '^| ACTIVE ' "$INDEX" || true)
count=$(printf '%s' "$active" | grep -c . || true)

if [ "$count" -eq 1 ]; then
  exit 0
fi

echo "check-index: expected exactly 1 ACTIVE plan, found $count" >&2
[ -n "$active" ] && printf '%s\n' "$active" | sed 's/^/  /' >&2
exit 2

Then we wire it into .claude/settings.json so it runs before every edit.

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [ { "type": "command", "command": "./workspace/bin/check-index.sh" } ] }
    ]
  }
}

We commit workspace/, CLAUDE.md and .claude/settings.json so a teammate gets all three with the clone, and we both start Claude Code in the repository root, since the hook’s path is relative.

The right side of the picture is the test. Sam adds plans/003-rate-limits.md as a second ACTIVE row above the DONE one, so the file now has ACTIVE on lines 10 and 11 and the finished plan on line 12. When I did that and asked an agent to edit a file, the edit was blocked and the agent was handed this:

check-index: expected exactly 1 ACTIVE plan, found 2
  10:| ACTIVE | plans/002-auth-migration.md | jc |
  11:| ACTIVE | plans/003-rate-limits.md | sam |

The agent can’t repair the index itself, because the same hook blocks that edit too, so one of us opens the file by hand and marks the finished plan DONE. I deleted the second row, asked for the same edit, and it went through with the script silent.

$ ./workspace/bin/check-index.sh; echo $?
0

We run that half too, since a check we have only ever seen block could be blocking everything.

The left side of the picture is where this grows, and its caption reads “six directories, one script”. The grey tags are chapter numbers from my book: index.md and plans/ are Ch3, owners.md is Ch6, scopes.md is Ch7, inbox/ is Ch4, proof/ is Ch5 and runlog/ is Ch8. Today we need only the two Ch3 entries and bin/check-index.sh, and I’d resist building the other five until a second person is really working in the repository.

Hand the repository to a teammate this weekend, and before you explain anything, have them ask their agent what the ACTIVE plan is.

Now go build something this weekend!

John Cook