Documentation

Everything needed to install Company Brain and bind your first repo.

What is Company Brain

Company Brain is a persistent context/memory management platform built for teams working with AI coding agents. Instead of an agent re-deriving your architecture, conventions, and prior decisions from scratch every session — or a human re-typing the same explanation into every new chat — that context lives centrally and is pulled in deliberately, once, by a CLI command.

It's built around one idea: reads and writes are asymmetric. Writing what an agent did is automatic and cheap — every session reports back. Reading is a deliberate, human-run action (cb pull) — nobody's agent silently inherits another agent's half-finished context mid-session.

The 4-level hierarchy

Company Context

Org-wide standards — coding conventions, architecture principles, design system. Read-only to agents; edited by humans (leads/PMs) in the app.

Project Context

What a specific project is supposed to do, its architecture, its expected flow. A project can span multiple repos (a monorepo or a shared library binds several).

Feature Context

Shared scratch space for one feature, visible to every agent — in every repo — working on it. A feature can be scoped to a project, or independent (org-level, cross-cutting or pre-project work).

Agent Context

A record of what an agent did, chained to prior agent contexts in the same lineage. This is how a fresh session — after a context-window hand-off — picks up exactly where the last one left off.

Architecture

Backend — Node/Express + Postgres (Drizzle ORM). Exposes REST, an MCP server, and OAuth 2.1 (for MCP clients that don't want to manage a token by hand).
Desktop app — Electron client for browsing/editing context documents, switching orgs, and resolving repo bindings visually.
cb CLI — resolves org/project/feature for a repo and pulls its context to disk. This is what makes onboarding a new repo a single deliberate command instead of a multi-minute back-and-forth with an agent.
Skill protocol — a SKILL.md that cb init installs into .claude/skills/company-brain/, which Claude Code auto-discovers and follows every session.

Installing the backend + desktop app

Clone the main repo and run everything with one script:

git clone https://github.com/Omzee15/Company-Brain.git
cd Company-Brain
cp backend/.env.example backend/.env
# fill in DATABASE_URL (Postgres/Neon) and JWT_SECRET in backend/.env
./run.sh

run.sh installs dependencies if needed, applies database migrations, then starts the backend (REST + MCP + OAuth, :4000) and the Electron desktop app (:5170) together. Requires pnpm and a Postgres connection string.

Installing the `cb` CLI

cd Company-Brain/cli
pnpm install
pnpm build
npm link            # or: pnpm link --global

That makes cb available on your PATH. Login isn't a required separate step — the first command that needs auth (usually cb init) will prompt for it inline and remember it globally in ~/.config/company-brain/credentials.json.

Connecting Claude Code (MCP)

The skill cb init installs still uses two live MCP calls — creating an agent context, and submitting knowledge updates. Connect once per machine:

claude mcp add --transport http company-brain <backend-url>/mcp \
  --header "Authorization: Bearer <token>"

Binding a new repo

cd your-repo         # must be a git repo
cb init               # picks org → project → feature, pulls context

git add .claude/skills/company-brain/SKILL.md
git commit -m "Add Company Brain skill"

Then just start Claude Code (claude) in that repo — it auto-discovers the skill, reads the local binding and context index, and reports what it connected to in one line before starting on the task.

cb command reference

Command	What it does
cb login	Authenticates and stores a token globally. Optional — most commands trigger it inline the first time it's needed. `--register` creates a new account; `--backend-url` overrides the default.
cb init	First-time repo setup. Picks org → project → feature, writes `.git/company-brain/config.json`, pulls context, and installs `.claude/skills/company-brain/SKILL.md`.
cb status	Login state, bound org/project/feature, and last pull time.
cb pull	Re-fetches the latest context for the currently bound project/feature. Nothing pulls automatically — this is deliberate.
cb org [switch]	Shows the bound org, or re-picks it (and project/feature) entirely.
cb project [switch]	Shows the bound project, or re-picks project + feature within the same org.
cb feature	Shows the current feature.
cb feature list	Lists project-scoped + independent features, marking the current one.
cb feature <name>	Switches to an existing feature by name and re-pulls its context.
cb feature -b <name>	Creates a new feature and switches to it in one step. Errors if `cb init` hasn't run yet.

What gets stored where

          .git/company-brain/
  config.json          # organizationId/Name, projectId/Name, featureId/Name, agentContextId
  context/
    index.json          # titles/categories only, plus recent knowledge updates
    company/*.md          # one file per company-level doc
    project/*.md            # one file per project-level doc
    feature/*.md              # one file per feature-level doc
        

Everything under .git/company-brain/ is local to the clone and never committed — the same principle as .git/config holding your remote URL. An agent reads index.json (titles only) first, then opens, selectively, only the specific files relevant to its task — not the entire context dump on every session.

The skill protocol, in short

Read the local binding (config.json) — no tool calls, just a file read. If it's missing, tell the user to run cb init and stop.
Read context/index.json, skim titles, open only the specific docs relevant to the task.
Start or resume an Agent Context via one MCP call, chaining to a prior lineage if one exists.
Do the work.
Offer to save a Chat Context write-up — on request at any time, or by asking after finishing a task.
Submit a Knowledge Update — always, before finishing — so the next agent (or a human) knows what happened.

Agent Contexts & categories

Besides the repo-bound Agent Context created by cb init, you can save and reload standalone context from any folder — bound or not — owned by you, not a project. These show up in the desktop app's Agent Contexts sidebar list.

Command	What it does
/cb-dump-context	Saves a summarized write-up of the current chat as a new unscoped Agent Context.
/cb-use-context [name]	Loads one back. With no argument, shows a numbered picker of everything you've saved. With a name, jumps straight to the matching one.
/cb-last-context	Loads your most recently saved context, no picking required.

Categorized by type

Every write-up — whether saved via /cb-dump-context or the repo-bound /cb-write-agent-context — is tagged with a type, so contexts stay sortable and searchable as they pile up:

Type	Used for
decision	A choice that was made, and why.
flow	A process, sequence, or how-something-works write-up.
finding	A fact, gotcha, bug, or insight tied to a specific moment.
topic	Evergreen reference knowledge, likely to be extended later.
dump	Catch-all — used when nothing else fits.

The agent infers the type from the conversation, or you can say it directly — /cb-dump-context decision. Under the hood this is just a prefix on the document's category field, e.g. decision-2026-08-18-auth-refactor — no separate type system, just a naming convention every write path follows.

Copying a context's name

In the desktop app, each row under Agent Contexts in the sidebar has a copy button next to it. Click it to copy that context's exact name to your clipboard, then paste it straight into /cb-use-context <name> — no need to retype it or hunt through the numbered picker.