Team Brain

Git-native shared AI memory for teams.

Your teammate debugged that issue yesterday. Your team decided on REST over GraphQL last month. Your codebase has conventions that every AI session ignores.

Team Brain fixes this. Record lessons, decisions, and conventions once — they're automatically loaded into every Claude Code session, for every team member. No servers. No accounts. Just git.

The Problem

AI coding agents are single-player:

• Your teammate spent 2 hours debugging a Stripe webhook — Claude doesn't know
• The team agreed to use async/await everywhere — Claude uses .then() anyway
• You onboarded a new dev — their Claude starts from absolute zero
• Architecture decisions live in Slack threads nobody can find

CLAUDE.md exists, but it's manually maintained and nobody updates it.

The Solution

Team Brain stores team knowledge in .team-brain/ and auto-generates a BRAIN.md that Claude reads every session. Commit it to git. Everyone on the team gets the same context.

.team-brain/
├── BRAIN.md                      # Auto-generated, Claude reads this
├── conventions/
│   └── always-use-async-await.md
├── decisions/
│   └── 001-rest-over-graphql.md
├── lessons/
│   └── 2026-03-30-stripe-webhook-retry.md
└── knowledge/
    └── api-rate-limits.md

Features

Record Lessons

/team-brain learn Stripe webhooks retry 3 times with exponential backoff

Claude captures the context from your current conversation, creates a structured entry, and regenerates BRAIN.md.

Record Decisions (ADR Format)

/team-brain decide Use REST over GraphQL for public API

Creates an Architecture Decision Record with Context, Decision, and Consequences sections.

Add Conventions

/team-brain convention Always use async/await, never .then() chains

Conventions get highest priority in BRAIN.md — Claude sees them first.

Search the Brain

/team-brain recall stripe webhooks

Keyword + fuzzy search across all entries. Returns the most relevant matches with context snippets.

Onboard New Developers

/team-brain onboard

Generates a comprehensive onboarding guide from all team brain entries — conventions, decisions, lessons, and project knowledge in one document.

Cross-Tool Generation

/team-brain sync              # Regenerate BRAIN.md
/team-brain sync cursorrules  # Also generate .cursorrules (for Cursor)
/team-brain sync agents       # Also generate AGENTS.md (universal standard)

Auto-Loading

Team Brain includes a SessionStart hook that automatically loads context at the beginning of every Claude Code session. If any entries are newer than BRAIN.md, it regenerates automatically.

Installation

Quick Install

git clone https://github.com/Manavarya09/team-brain.git ~/.claude/plugins/team-brain

Add the SessionStart hook to your settings

Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash ~/.claude/plugins/team-brain/hooks/load-brain.sh"
        }]
      }
    ]
  }
}

Initialize in your project

/team-brain init

This creates .team-brain/ in your repo root. Commit it to git.

Usage

Quick Start

# Initialize team brain in your project
/team-brain init

# Add your first convention
/team-brain convention Use TypeScript strict mode everywhere

# Record a lesson from today's debugging
/team-brain learn React useEffect cleanup runs on unmount AND re-render

# Record an architecture decision
/team-brain decide Use Zod for runtime validation at API boundaries

# Commit and push so teammates get the context
git add .team-brain/ && git commit -m "team-brain: add initial conventions and decisions"
git push

For Teammates

# Pull latest team brain entries
git pull

# Context loads automatically on next Claude Code session
# Or manually sync:
/team-brain sync

Search and Recall

/team-brain recall validation     # Search for entries about validation
/team-brain recall                # Show recent entries
/team-brain status                # Show stats and contributor info

Entry Format

Every entry is a markdown file with YAML frontmatter:

---
title: Stripe webhooks retry 3 times with exponential backoff
type: lesson
author: manavarya
date: 2026-03-30
tags: [stripe, webhooks, payments]
status: active
---

## Context
Spent 2 hours debugging why payment confirmations were duplicated.

## Detail
Stripe retries failed webhook deliveries 3 times over 24 hours.
Our handler wasn't idempotent, causing duplicate order processing.
Fixed by checking idempotency key before processing.

## Related
- PR #47: Add idempotency check to webhook handler

Entry Types

How It Works

1. You record knowledge via /team-brain learn, /team-brain decide, or /team-brain convention
2. Entries are saved as markdown files in .team-brain/
3. BRAIN.md is auto-generated — a prioritized summary under 180 lines
4. On session start, the hook loads BRAIN.md into Claude's context
5. Teammates pull via git and get the same context
6. Optionally generates .cursorrules (Cursor) and AGENTS.md (universal)

Why 180 Lines?

Claude Code applies instructions from context files with ~92% accuracy under 200 lines. Above 400 lines, accuracy drops to ~71%. Team Brain auto-prioritizes (conventions > decisions > lessons > knowledge) and caps BRAIN.md at 180 lines to stay in the sweet spot.

Configuration

Settings are in .team-brain/config.json:

{
  "brain_max_lines": 180,
  "auto_generate": true,
  "inject_into_claude_md": true,
  "generate_cursorrules": false,
  "generate_agents_md": false,
  "priority_order": ["conventions", "decisions", "lessons", "knowledge"],
  "max_entries_per_section": 20,
  "include_dates": true,
  "include_authors": true
}

Requirements

• Claude Code (any version with skill/hook support)
• Node.js (ships with Claude Code)
• Git (for sharing with teammates)

FAQ

Q: How is this different from just editing CLAUDE.md?
A: CLAUDE.md is static and manually maintained. Team Brain auto-generates it from structured entries, stays under the 180-line sweet spot, and makes it easy for any team member to contribute knowledge without editing a shared file.

Q: What happens when two people add entries on the same branch?
A: Each entry is its own file, so git merges cleanly. BRAIN.md is auto-generated, so even if it conflicts, running /team-brain sync regenerates it.

Q: Does this work with Cursor / Copilot?
A: Yes. Run /team-brain sync cursorrules to generate .cursorrules for Cursor. Run /team-brain sync agents to generate AGENTS.md which Copilot and other tools read.

Q: Will this slow down my sessions?
A: The SessionStart hook runs in under 100ms. It only regenerates BRAIN.md if entries have changed.

Q: Where is the data stored?
A: Everything is in .team-brain/ in your repo root. It's just files in git — no databases, no cloud, no external services.

Contributing

See CONTRIBUTING.md for guidelines.

Areas where help is needed:

• Auto-learn hook: detect patterns worth remembering from tool output
• Conflict resolution UI for BRAIN.md merge conflicts
• Team analytics dashboard (who's contributing, coverage gaps)
• Integration with Linear/Jira for linking entries to tickets
• VS Code extension for browsing team brain entries

License

MIT License. See LICENSE for details.

Your AI should know what your team knows.