How to use Claude Code with multiple repositories without losing context

Posted on by — No Comments ↓

How to use Claude Code with multiple repositories without losing context

If you work across multiple repos — a frontend, a backend, a shared library — you already know the pain: Claude Code loses track of which project you’re in, forgets the conventions from the other repo, and you spend half your session re-explaining things it already knew.

Here’s how to fix it.

The core problem: Claude Code has one context window

Claude Code doesn’t have persistent memory across sessions or across repositories. When you open a new project, it starts fresh. When you switch from your API repo to your frontend repo mid-session, context from the first repo doesn’t automatically transfer.

This becomes a real problem when:

  • Your API and frontend share types but live in different repos
  • You need to make coordinated changes across both repos simultaneously
  • Your backend conventions differ from your frontend conventions
  • You’re doing a migration that touches multiple codebases

Solution 1: The shared CLAUDE.md strategy

Create a root-level CLAUDE.md in each repo that cross-references the other: 

# API Repo - CLAUDE.md

## This project
REST API using Node.js + Express + PostgreSQL
Auth: JWT tokens, 15min access / 7day refresh

## Paired with: frontend repo at ../frontend
Frontend expects:
- All API responses: { data: ..., error: null } or { data: null, error: "message" }
- Date format: ISO 8601 strings (not timestamps)
- Auth header: Bearer {accessToken}

## Shared types
See ../shared-types/index.ts for TypeScript interfaces
Any API change that affects response shape MUST update shared-types first

And in the frontend: 

# Frontend Repo - CLAUDE.md

## This project
Next.js 14 + TypeScript + Tailwind

## Paired with: API repo at ../api
API base URL: http://localhost:3001
All fetch calls use: src/lib/api.ts (do not call fetch directly)
Error handling: check error field on response, never .catch() alone

## When making API changes
1. Check ../api/CLAUDE.md for response format
2. Update src/types/ to match any schema changes
3. Update src/lib/api.ts if adding new endpoints

Now when Claude Code reads your CLAUDE.md, it immediately understands the cross-repo relationship.

Solution 2: The context handoff file

When you’re actively working across repos, create a temporary CONTEXT.md at your workspace root: 

workspace/
  CONTEXT.md      ← Claude reads this first
  api/
  frontend/
  shared-types/

# Active work context - 2026-04-08

## Current task
Adding user avatar upload feature
- API changes: POST /api/users/avatar, returns { avatarUrl: string }
- Frontend changes: ProfilePage.tsx needs upload button + preview
- Database: Added avatar_url column to users table (migration already run)

## Status
- [x] Database migration done
- [x] API endpoint done (api/src/routes/users.js)
- [ ] Frontend upload component (next: frontend/src/components/AvatarUpload.tsx)
- [ ] Wire up to ProfilePage

## Constraints remembered
- Max file size: 5MB (enforced in API, also validate in frontend)
- Accepted types: image/jpeg, image/png, image/webp only
- CDN URL pattern: https://cdn.example.com/avatars/{userId}.{ext}

Start each Claude Code session with: “Read CONTEXT.md first, then let’s continue.”

Solution 3: Run parallel instances with clear boundaries

For large cross-repo tasks, run two Claude Code instances simultaneously: 

# Terminal 1 - API work
cd /workspace/api
claude

# Terminal 2 - Frontend work  
cd /workspace/frontend
claude

Give each instance a single responsibility:

  • API instance: “You own the backend changes. Output the exact response shape when you’re done.”
  • Frontend instance: “The API will return X shape. You own the frontend. Don’t modify API files.”

Then consolidate by feeding the output from one into the other.

Solution 4: The contract file pattern

For ongoing multi-repo projects, create an explicit API contract file that both repos reference: 

// shared-types/contract.ts
// SOURCE OF TRUTH - both repos import from here

export interface ApiResponse<T> {
  data: T | null;
  error: string | null;
  timestamp: string; // ISO 8601
}

export interface User {
  id: string;
  email: string;
  avatarUrl: string | null;
  createdAt: string;
}

export interface AuthTokens {
  accessToken: string;  // expires: 15 minutes
  refreshToken: string; // expires: 7 days
}

Both CLAUDE.md files reference this contract: 

## Shared contract
See ../shared-types/contract.ts — this is the source of truth.
Never duplicate type definitions. Import from shared-types.

When Claude Code reads your CLAUDE.md and then checks shared-types/contract.ts, it understands the full system without you explaining anything.

The rate limit problem

The real challenge with multi-repo work: you burn through context FAST.

Explaining two repos, their conventions, their shared types, the active task — that’s a lot of tokens before you write a single line of code. When you’re working across 3+ repos, you can hit rate limits mid-task.

The ANTHROPIC_BASE_URL environment variable lets you point Claude Code at a different API endpoint: 

export ANTHROPIC_BASE_URL=https://simplylouie.com/api/proxy
claude

SimplyLouie runs at ✌️$2/month (vs $200 for Claude Max) and is specifically built for developers who run long, context-heavy sessions. The proxy handles the rate limit ceiling so your multi-repo sessions don’t get cut off mid-task.

Practical workflow that works

  1. Before starting: Write CONTEXT.md with current task, status, constraints
  2. Each session: claude → “Read CONTEXT.md and CLAUDE.md first”
  3. When switching repos: Update CONTEXT.md with what you just completed
  4. For coordinated changes: Run parallel instances with clear boundaries
  5. For shared types: Keep a contract file that both CLAUDEs reference

The extra 2 minutes writing CONTEXT.md saves 20 minutes of re-explaining. And with a stable API endpoint that doesn’t rate-limit mid-session, you can actually finish cross-repo tasks in one sitting.

Working across multiple repos? What’s your current strategy for keeping Claude Code on track?

Leave a Reply