Shadow Branch Pattern

Think in code.
Publish clean code.

Git Shadow separates your local thinking layer from your collaboration layer — automatically. Write the comments and notes you need. Publish only what your team needs to read.

Get started Learn the pattern

feature/login@local → feature/login your thinking layer your collaboration layer

Every developer has two kinds of code

Code for thinking

Exploratory comments. Algorithm sketches. Architecture notes. Debug helpers. AI memory files.

These structures help you reason during development — but they're often considered noise in a shared repository.

Code for collaboration

Clean commits. Reviewable diffs. Maintainable history.

The code your team shares, reviews, and maintains over time.

Until now, you had to choose between them.
Git Shadow removes that compromise.

The Shadow Branch Pattern

One feature. Two branches.

For each feature, Git Shadow maintains two parallel branches — one for your thinking, one for your team.

feature/login@local local thinking layer

feature/login collaboration layer → push to remote

Your @local branch can contain design comments, pseudo-code, architecture notes, debugging helpers, AI memory files — anything that helps you think. The published branch remains clean and reviewable.

Read the full pattern documentation →

Three commands. Full workflow.

git shadow new-feature feature/login

Creates both feature/login and feature/login@local. Switches you to the local branch.

Work on @local

Write your code. Add /// comments freely — algorithm steps, decision notes, AI context. No restrictions.

git shadow publish --commit -m "feat(auth): login"

Strips local comments. Creates clean commits. Cherry-picks to the public branch. Push normally with git push.

Write the code you need to think

Your @local branch. Free to annotate.

feature/login@local

  /// Get user from database
  const user = await prisma.user.findUnique({
    where: { email },
  })
  if (!user) throw new Error('Invalid credentials')

  /// Verify account status
  if (!user.isActive) throw new Error('Account disabled')

  /// Verify password hash
  const valid = await bcrypt.compare(password, user.passwordHash)
  if (!valid) throw new Error('Invalid credentials')

  /// Build and return session
  return prisma.session.create({ data: { userId: user.id } })

→

feature/login — published

  const user = await prisma.user.findUnique({
    where: { email },
  })
  if (!user) throw new Error('Invalid credentials')

  if (!user.isActive) throw new Error('Account disabled')

  const valid = await bcrypt.compare(password, user.passwordHash)
  if (!valid) throw new Error('Invalid credentials')

  return prisma.session.create({ data: { userId: user.id } })

What you get

⬡

Free to think

Write every comment, note, and helper you need. No self-censorship. No cleanup tax.

⬡

Clean by default

Published branches are always clean. One command handles the stripping and cherry-picking.

⬡

Just Git

No external services. No proprietary formats. Pure shell scripts on top of Git.

⬡

AI memory layer

The @local branch becomes a versioned, inspectable cognitive workspace for you and your AI tools.

AI-assisted development

A transparent memory layer for AI

AI tools have no persistent, transparent memory of your project. You reintroduce context every session. The AI builds assumptions you can't see or correct.

The @local shadow branch solves this. AI reasoning lives next to the code — visible, versioned, editable. Not hidden in prompts. Not locked inside proprietary agents.

Git Shadow allows developers to observe, shape, and version the evolving memory of AI working on their codebase.

Explore the AI memory layer concept →

Think in code.Publish clean code.