Chapter 29: Branch Context System

Evidence: Production MASTER-PLAN - 47-70% token savings per branch Difficulty: Intermediate Time: 30 minutes setup ROI: 30-50% context reduction per branch

Problem

Loading ALL context files for ALL branches wastes tokens:

dev-Data needs database patterns, not UI patterns
dev-UI needs frontend patterns, not sync patterns
Loading everything = 116k+ tokens (context bloat)

Solution: CONTEXT-MANIFEST.json

Each branch gets a manifest defining EXACTLY what to load.

File Location

CURRENT/{branch}/CONTEXT-MANIFEST.json

Structure

{
  "manifest_version": "3.0",
  "branch": "dev-Knowledge",
  "mission": "Skills, Context, Agents & MCP Optimization",
  "domain": "knowledge-optimization",
  
  "ondemand_files": {
    "branch_context": [
      "CURRENT/dev-Knowledge/dev-Knowledge-ROADMAP.md"
    ],
    "skills-dev": [
      "skills-dev/creation-standards.md",
      "skills-dev/trigger-keywords.md"
    ],
    "context": [
      "context/CONTEXT-SYSTEM-GUIDE-MINI.md"
    ]
  },
  
  "estimated_tokens": {
    "global_always": 64000,
    "ondemand_domain": 15000,
    "total_max": 79000
  },
  
  "should_NOT_load": {
    "deployment/ci-cd.md": "Not managing CI/CD (dev-MERGE domain)",
    "database/COMPLETE-SCHEMA.md": "Too large - using QUICK-REFERENCE instead"
  }
}

@ Import Enforcement

The manifest powers automatic file loading via @ imports.

How It Works

Session starts → Hook detects branch
Hook reads → CURRENT/{branch}/CONTEXT-MANIFEST.json
Hook generates → @ imports in CLAUDE.md
Claude Code → Auto-loads @ imported files

Hook Logic (session-start.sh)

CRITICAL: The hook must WRITE to CLAUDE.md, not just print to terminal! The @ symbol only triggers file loading when it’s IN CLAUDE.md.

#!/bin/bash
# .claude/hooks/session-start.sh

current_branch=$(git branch --show-current 2>/dev/null)
manifest="CURRENT/$current_branch/CONTEXT-MANIFEST.json"

# STEP 1: CLEANUP - Remove old sections to prevent accumulation
if [ -f "CLAUDE.md" ]; then
    if grep -q "AUTO-LOADED DOMAIN FILES" CLAUDE.md 2>/dev/null; then
        sed -i '/^## 🔄 AUTO-LOADED DOMAIN FILES/,$d' CLAUDE.md
    fi
fi

# STEP 2: WRITE @ imports to CLAUDE.md (NOT just display!)
if [ -f "$manifest" ]; then
    # Write section header TO CLAUDE.md
    cat >> CLAUDE.md << EOF

---

## 🔄 AUTO-LOADED DOMAIN FILES (Session-Specific)

**Branch**: $current_branch
**Source**: $manifest

EOF

    # Extract files and WRITE @ imports TO CLAUDE.md
    jq -r '.ondemand_files | to_entries[] | .value[]' "$manifest" 2>/dev/null | while read file; do
        [ -z "$file" ] && continue

        # Handle absolute vs relative paths
        if [[ "$file" == CURRENT/* ]] || [[ "$file" == memory-bank/* ]]; then
            FULL_PATH="$file"
        else
            FULL_PATH="memory-bank/ondemand/$file"
        fi

        # Write @import if file exists
        [ -f "$FULL_PATH" ] && echo "@$FULL_PATH" >> CLAUDE.md
    done

    echo "" >> CLAUDE.md
    echo "_Auto-generated @ imports from CONTEXT-MANIFEST.json_" >> CLAUDE.md

    # Also display for user visibility
    echo "═══ AUTO-LOADED: $(jq -r '[.ondemand_files | to_entries[] | .value[]] | length' "$manifest") files from $manifest ═══"
fi

Key Difference:

❌ echo "@$file" - Prints to terminal (files NOT loaded)
✅ echo "@$file" >> CLAUDE.md - Writes to file (files ARE loaded)

Result in CLAUDE.md

## 🔄 AUTO-LOADED DOMAIN FILES (Session-Specific)

**Branch**: dev-Knowledge

**Auto-loaded from**: CURRENT/dev-Knowledge/CONTEXT-MANIFEST.json

@CURRENT/dev-Knowledge/dev-Knowledge-ROADMAP.md
@memory-bank/ondemand/skills-dev/creation-standards.md
@memory-bank/ondemand/skills-dev/trigger-keywords.md
@memory-bank/ondemand/context/CONTEXT-SYSTEM-GUIDE-MINI.md

Token Savings Results

Branch	Before	After	Savings
dev-Knowledge	116k	79k	32%
dev-feature	126k	79k	37%
dev-UI	100k	53k	47%
dev-Data	110k	75k	32%
Average	113k	72k	37%

Setup Steps

Step 1: Create Branch Directory

mkdir -p CURRENT/{branch-name}

Step 2: Create Manifest

cat > CURRENT/{branch-name}/CONTEXT-MANIFEST.json << 'EOF'
{
  "manifest_version": "3.0",
  "branch": "{branch-name}",
  "mission": "[One sentence mission]",
  "domain": "[domain-name]",
  
  "ondemand_files": {
    "branch_context": [
      "CURRENT/{branch-name}/{branch-name}-ROADMAP.md"
    ]
  },
  
  "estimated_tokens": {
    "global_always": 64000,
    "ondemand_domain": 10000,
    "total_max": 74000
  }
}
EOF

Step 3: Add Session-Start Hook

Copy the hook logic above to .claude/hooks/session-start.sh

Step 4: Validate

# Switch to branch
git checkout {branch-name}

# Run hook manually
bash .claude/hooks/session-start.sh

# Verify @ imports appear
grep "^@" CLAUDE.md

Best Practices

1. Keep Manifests Focused

DO: 5-15 files per branch

"ondemand_files": {
  "branch_context": ["...ROADMAP.md"],
  "domain": ["quick-reference.md", "patterns.md"]
}

DON’T: Load everything

"ondemand_files": {
  "everything": ["file1.md", "file2.md", ... "file50.md"]
}

2. Use should_NOT_load

Document WHY certain files are excluded:

"should_NOT_load": {
  "deployment/ci-cd.md": "Not managing CI/CD (dev-MERGE domain)",
  "database/COMPLETE-SCHEMA.md": "Too large (96k!) - use QUICK-REFERENCE"
}

3. Track Token Budgets

"estimated_tokens": {
  "global_always": 64000,
  "ondemand_domain": 15000,
  "total_max": 79000,
  "status": "OPTIMIZED - 33k tokens saved"
}

Validation Commands

# Check manifest exists
ls CURRENT/$(git branch --show-current)/CONTEXT-MANIFEST.json

# View loaded files
jq '.ondemand_files' CURRENT/$(git branch --show-current)/CONTEXT-MANIFEST.json

# Count files per branch
jq '[.ondemand_files | to_entries[] | .value | length] | add' CURRENT/*/CONTEXT-MANIFEST.json

# Check context usage in Claude Code
/context

Template

See template/CURRENT/{branch}/CONTEXT-MANIFEST.json for a ready-to-use template.

Related Chapters:

Chapter 12: Memory Bank Hierarchy (4-tier structure)
Chapter 26: Claude Code Rules System (rules loading)
Chapter 30: Blueprint Auto-Loading (per-branch blueprints)
Chapter 31: Branch-Aware Development (branch-variables.json)

Previous: 28: Skill Optimization Patterns Next: 30: Blueprint Auto-Loading