.context/ Worktree Pattern

context-worktree-pattern.md

.context/ Worktree Pattern

A git pattern for keeping markdown context files (docs, specs, decisions, notes) in the same repo as code but on a completely separate history.

What it is

An orphan git branch mounted as .context/ via git worktree. Context and code share the same repo but have fully separate histories. Markdown files on the context branch are accessible to both humans and AI agents alongside the codebase, without cluttering the main branch or polluting the code commit log.

Setup

# Gitignore first so the worktree doesn't show as untracked
echo ".context/" >> .gitignore
git add .gitignore && git commit -m "gitignore .context/"

# Create the orphan branch (no shared history with main)
git checkout --orphan context
git rm -rf .
# Note: git rm -rf . only clears the index. Files from main remain on disk
# as untracked. They'll disappear when you return to main below.
git commit --allow-empty -m "init context branch"
git checkout main

# Mount as a persistent directory
git worktree add .context context

# Push to remote
git push -u origin context

New team member after clone:

git worktree add .context context

Maintenance

git worktree list              # see active worktrees
git worktree remove .context   # clean teardown
git worktree prune             # clean up stale worktree metadata

How it works

.context/ appears as a normal directory in the project root. Any tool — editor, CLI, AI agent — can read and write files in it like any other directory. But under the hood it's a separate branch with its own commit history.

Updating context:

git -C .context add .
git -C .context commit -m "description of change"
git -C .context push

Getting latest from others:

git -C .context pull

Switching code branches (checkout, rebase, merge on main/feature branches) does not touch .context/. It's pinned to the context branch. Both sides can evolve independently.

Why this works

• No infrastructure. Just markdown files, git, and one setup command.
• Worktree is invisible. .context/ is a normal directory — standard tools work.
• Separate histories. Context commits never pollute the code log. Code commits never touch context.
• Branch-agnostic. Code can be on any branch; .context/ is always accessible.
• Scales to teams. Push/pull to remote. Multiple people can write to context without interfering with code work.
• No docs bloat in the codebase. Markdown files, specs, notes, and supporting documents stay out of the main tree entirely.
• Composes with Claude Code's worktree handling. Claude Code is worktree-aware natively — adding .context/ doesn't confuse its git-root detection or memory anchoring.

Use cases

• Project documentation that evolves independently from code releases
• Specs and supporting documents that would otherwise go stale or clutter the codebase
• Any recurring AI-assisted workflow that needs continuity across sessions
• Separating human-targeted and agent-targeted content in the same repo

Extending with junctions / symlinks

Some tools expect files at a specific path (e.g., Claude Code loads skills from .claude/skills/). A junction (Windows) or symlink (macOS/Linux) can bridge the expected path to the actual files on the context branch.

# Windows (no admin needed) — absolute path, same drive as the repo
cmd /c "mklink /J .claude\skills C:\absolute\path\to\repo\.context\skills"

# macOS / Linux
ln -s ../.context/skills .claude/skills

The tool reads from .claude/skills/ as usual. The files actually live in .context/skills/ on the orphan branch. Auto-discovery, hot-loading, and editing all work transparently through the junction.

Gotchas:

• On Windows, junctions can't cross drives. If the repo is on D: and the path points to C:, the junction silently fails or produces a broken link. Use the same drive as the repo.
• Windows junctions require absolute paths to resolve correctly.

Gitignore the junction target (e.g., .claude/skills/) on main, not the whole parent directory. Other files in .claude/ like settings.json or commands/ may be team-shared config you want to commit. Target the junction specifically:

echo ".claude/skills/" >> .gitignore

Alternatives considered

Approach	Why not
Docs on main	Pollutes code commit log. Docs change at different cadence than code.
Separate repo	Files outside project root. Coordination overhead. Harder for agents to access.
Submodule	Two-commit dance. Sync issues. Windows edge cases.
Subtree	Context commits interleave with code history. Slow on Windows.