Skip to content

Bootstrap Guide

How to set up Jerry's context distribution after cloning.

Document Sections

Section Purpose
Overview What bootstrap does and why
Quick Start Get set up in 30 seconds
How It Works Architecture of .context/ and .claude/
Platform Notes macOS, Linux, Windows differences
Troubleshooting Common issues and fixes
Rollback How to undo the bootstrap

Overview

Jerry stores its behavioral rules and pattern catalog in .context/ (the canonical source). Claude Code reads them from .claude/rules/ and .claude/patterns/. The bootstrap process syncs the two using platform-aware linking.

Why two directories?

  • .context/ is the canonical source - version-controlled and distributable
  • .claude/ is where Claude Code looks for auto-loaded rules and settings
  • Symlinks connect them so edits in either location propagate instantly

Quick Start

After cloning the repository:

# Full setup (includes bootstrap)
make setup

# Or bootstrap only
uv run python scripts/bootstrap_context.py

# Verify it worked
uv run python scripts/bootstrap_context.py --check

You should see:

Checking Jerry context sync status...

  rules: linked -> /path/to/jerry/.context/rules
  patterns: linked -> /path/to/jerry/.context/patterns

Status: OK

How It Works

.context/                          .claude/
├── rules/  ──── symlink ────►    ├── rules/
├── patterns/ ── symlink ────►    ├── patterns/
└── templates/                     ├── agents/    (untouched)
                                   ├── commands/  (untouched)
                                   └── settings.json (untouched)

The bootstrap script (scripts/bootstrap_context.py) uses a platform-aware strategy:

Platform Linking Method Notes
macOS Relative symlinks Instant, auto-propagating
Linux Relative symlinks Same as macOS
Windows (Developer Mode) Symlinks Requires Developer Mode enabled
Windows (standard) Junction points No admin required, directories only
Fallback File copy Works everywhere, requires re-sync on changes

Platform Notes

macOS / Linux

Symlinks work out of the box. No special configuration needed.

Windows

The script tries symlinks first (works with Developer Mode enabled), then falls back to junction points. Junction points:

  • Work without admin privileges
  • Only work for directories (which is all we need)
  • Must be on the same drive as the source
  • Propagate changes instantly, like symlinks

To enable Developer Mode (for symlinks): Settings > Update & Security > For developers > Developer Mode

Git Worktrees

When using git worktrees, run bootstrap in each worktree:

cd ../my-worktree
uv run python scripts/bootstrap_context.py

Troubleshooting

"Could not find Jerry project root"

You're not in the Jerry repository directory, or CLAUDE.md / .context/ is missing. Make sure you cloned the full repo and are running from the project root.

"already linked"

You're already set up. Run --check to verify, or --force to re-link.

"drift detected"

Files in .claude/rules/ don't match .context/rules/. This happens with file-copy setups (no symlinks). Re-run the bootstrap to re-sync:

uv run python scripts/bootstrap_context.py --force

Windows junction point fails

Ensure you're on the same drive as the repository. If that doesn't work, try running from an elevated prompt.

Rollback

To undo the bootstrap and restore .claude/rules/ and .claude/patterns/ as regular directories:

# 1. Remove the symlinks/junctions
rm .claude/rules .claude/patterns        # macOS/Linux
# On Windows: rmdir .claude\rules .claude\patterns

# 2. Copy files back
cp -r .context/rules .claude/rules
cp -r .context/patterns .claude/patterns

To fully reverse the restructure (move canonical source back to .claude/):

# Remove symlinks
rm .claude/rules .claude/patterns

# Move canonical files back
mv .context/rules .claude/rules
mv .context/patterns .claude/patterns

After rollback, Claude Code will still read rules from .claude/rules/ as before.

Command Reference

Command What It Does
uv run python scripts/bootstrap_context.py Full bootstrap
uv run python scripts/bootstrap_context.py --check Verify sync status
uv run python scripts/bootstrap_context.py --force Re-sync (overwrites existing)
uv run python scripts/bootstrap_context.py --quiet Minimal output (for CI)