Skip to content

CLAUDE.md

Latest commit

 

History

History
101 lines (72 loc) · 5.35 KB

CLAUDE.md

File metadata and controls

101 lines (72 loc) · 5.35 KB

CLAUDE.md — Agent Instructions for Open Brain

This file helps AI coding tools (Claude Code, Codex, Cursor, etc.) work effectively in this repo.

What This Repo Is

Open Brain is a persistent AI memory system — one database (Supabase + pgvector), one MCP protocol, any AI client. This repo contains the extensions, recipes, schemas, dashboards, integrations, and skills that the community builds on top of the core Open Brain setup.

License: FSL-1.1-MIT. No commercial derivative works. Keep this in mind when generating code or suggesting dependencies.

Repo Structure

extensions/     — Curated, ordered learning path (6 builds). Do NOT add without maintainer approval.
primitives/     — Reusable concept guides (must be referenced by 2+ extensions). Curated.
recipes/        — Standalone capability builds. Open for community contributions.
schemas/        — Database table extensions. Open.
dashboards/     — Frontend templates (Vercel/Netlify). Open.
integrations/   — MCP extensions, webhooks, capture sources. Open.
skills/         — Reusable AI client skills and prompt packs. Open.
docs/           — Setup guides, FAQ, companion prompts.
resources/      — Official companion files and packaged exports.

Every contribution lives in its own subfolder under the right category and must include README.md + metadata.json.

Parallel Agent Worktrees

When multiple AI agents or assistant chats work on this repo, do not put them in the same checkout.

Setup pattern

  • Treat the main repo checkout as the canonical repo for pulling, inspection, and creating worktrees.
  • Create one Git worktree per active agent, task, or PR-sized workstream.
  • Give each worktree a descriptive folder name and a matching branch name.
  • Start every agent task by naming the exact absolute worktree path it owns.
  • The assigned worktree path is the boundary. The chat is not the boundary.

Agent assignment template

Start each parallel-agent task with:

Repository worktree:
/ABSOLUTE/PATH/TO/PROJECT-WORKTREE

Branch:
codex/SHORT-TASK-NAME

Task:
DESCRIBE THE EXACT WORK.

Rules

  • Do not switch branches in the canonical repo while another agent may be working.
  • Do not edit sibling worktrees unless explicitly asked.
  • Before staging or committing, run git status --short and stage only files that belong to the current task.
  • If main or another branch changed underneath the worktree, pause before merging or rebasing unless the task explicitly says to finish the PR end to end.
  • After a branch is merged and the worktree is clean, remove the finished worktree with git worktree remove /ABSOLUTE/PATH/TO/PROJECT-WORKTREE.

Quick checks

  • If another chat suddenly changed branches, both chats were probably in the same working directory.
  • If git worktree add says a branch is already checked out, create a new branch name or remove the old clean worktree.
  • If cleanup fails, inspect git status --short and preserve uncommitted work.

Guard Rails

  • Never modify the core thoughts table structure. Adding columns is fine; altering or dropping existing ones is not.
  • No credentials, API keys, or secrets in any file. Use environment variables.
  • No binary blobs over 1MB. No .exe, .dmg, .zip, .tar.gz.
  • No DROP TABLE, DROP DATABASE, TRUNCATE, or unqualified DELETE FROM in SQL files.
  • Avoid profanity in all content. Keep docs, examples, seed data, UI copy, prompts, walkthroughs, and generated assets clean and professional.
  • MCP servers must be remote (Supabase Edge Functions), not local. Never use claude_desktop_config.json, StdioServerTransport, or local Node.js servers. All extensions deploy as Edge Functions and connect via Claude Desktop's custom connectors UI (Settings → Connectors → Add custom connector → paste URL). See docs/01-getting-started.md Step 7 for the pattern.

PR Standards

  • Title format: [category] Short description (e.g., [recipes] Email history import via Gmail API, [skills] Panning for Gold standalone skill pack)
  • Branch convention: contrib/<github-username>/<short-description>
  • Commit prefixes: [category] matching the contribution type
  • Every PR must pass the automated review checks in .github/workflows/ob1-gate-v2.yml before human review
  • See CONTRIBUTING.md for the full review process, metadata.json template, and README requirements

Key Files

  • CONTRIBUTING.md — Source of truth for contribution rules, metadata format, and the review process
  • .github/workflows/ob1-gate-v2.yml — Automated PR gate
  • .github/workflows/claude-review.yml — Maintainer-triggered Claude PR review
  • .github/metadata.schema.json — JSON schema for metadata.json validation
  • .github/PULL_REQUEST_TEMPLATE.md — PR description template
  • LICENSE.md — FSL-1.1-MIT terms

Local GSD Execution Layer

This repo also has a maintainer-local GSD layer in .planning/.

  • If .planning/ exists, use it for local brownfield planning and phased execution.
  • Start with .planning/STATE.md, then read .planning/PROJECT.md, .planning/ROADMAP.md, and the relevant .planning/codebase/*.md documents.
  • Keep .planning/ local. It is gitignored intentionally and is not part of the public contribution contract or upstream PR scope.
  • Public contributor rules still come from CLAUDE.md, AGENTS.md, CONTRIBUTING.md, and the committed repo files.