cognition

A company brain. The CEO scaffolds it, every engineer joins it, every Claude Code session writes activity + skills back into the same repo. Open the wiki — see what everyone is working on, transparently.

npm i -g cognition-cli

# CEO / founder — once per company
cognition init

# Engineer / contributor — once per company you join
cognition link <repo-url>

# Engineer — turn on capture inside any code repo you work in
cognition wire <path-to-repo>

The CEO scaffolds the substrate (5 questions, ~3 minutes, live wiki). Each engineer joins it (4 questions, ~30 seconds, person page committed to the brain). Engineers wire their actual code repos so CC sessions inside acme-api log activity back to acme-company-brain.

Both flows install a per-company shim so typing <slug> from any directory enters that brain and runs claude.

How transparency works

Every CC session that runs inside a linked brain — or inside a wired code repo — leaves two artifacts:

1. Activity log. brain/activity/<your-slug>/<YYYY-MM-DD>--<session-id>.md gets the task, tool counts, and a link to any skill captured. Auto-committed and pushed to the brain repo.
2. Skill (when reusable). If the session looks like a non-trivial reusable solve, the Stop hook prompts you for a title and writes brain/skills/<slug>.md.

The CEO opens the wiki and sees the activity tab populate with everyone's recent work, indexed by person. Future CC sessions call cognition_find_skills (an MCP tool the brain ships with) to surface existing team skills before improvising — the brain gets sharper as the team works.

No phone-home. No external CLO. No accounts. Transparency is structural because the brain repo IS the substrate.

What you get

A Next.js 15 repo where every markdown file in brain/ is a wiki page.

your-company-brain/
├── brain/
│   ├── people/         one .md per teammate
│   ├── services/       one .md per stack component (Postgres, Stripe, ...)
│   ├── skills/         one .md per technical capability
│   ├── decisions/      one .md per architectural decision + rationale
│   ├── runbooks/       one .md per "when X breaks, do Y" playbook
│   └── files/          one .md per important source file, summarized
├── src/app/            Next.js wiki UI (reads brain/ at build time)
└── CLAUDE.md           tells future `claude` runs how to maintain it

The directory name is the kind. The filename (sans .md) is the slug. Add new top-level directories under brain/ and they show up as new tabs on the site automatically.

How cognition init works

1.  Asks 5 questions
    company name + slug
    one-sentence description
    top services in your stack
    repos to ingest
    where to scaffold

2.  Scaffolds the brain repo
    copies a Next.js + gray-matter + marked template
    creates empty brain/ subdirs
    drops a primer for Claude

3.  Hands off to your Claude Code
    npm install
    walks the repos you specified
    writes 30-80 markdown pages into brain/<kind>/<slug>.md
    git init + first commit

4.  Ships
    gh repo create <slug>-company-brain --public --source=. --push
    vercel deploy --prod

You watch your terminal scroll for ~3 minutes. At the end you have a live wiki, a public GitHub repo, and a Vercel deploy. All yours.

cognition init also installs a per-company shim — a one-line script on your PATH named after the slug. From that point on, typing <slug> from anywhere on your machine cds into the brain repo and runs claude.

How cognition link works (engineer flow)

Joining an existing brain. Bob is a new engineer at Acme; the brain already exists at github.com/acme/acme-company-brain.

$ cognition link https://github.com/acme/acme-company-brain

  cognition link · join an existing brain

  cloning https://github.com/acme/acme-company-brain
    → /Users/bob/code/acme-company-brain
  ✓ cloned

  who are you in this company?
  1/4 — full name (Bob Smith) > Bob Smith
  2/4 — role (engineer/founder/designer/pm) (engineer) > engineer
  3/4 — strong areas (comma-separated) > backend, postgres, payments, on-call
  4/4 — slack handle (optional, blank to skip) > @bob

  ✓ wrote brain/people/bob-smith.md
  ✓ committed + pushed
  ✓ acme shim installed
    /Users/bob/.local/bin/acme

  you're in. type acme from anywhere to enter the brain.

What this does, top to bottom:

1. Clones the brain repo to ~/code/<slug>-company-brain (override with a second positional arg).
2. Asks 4 questions to identify Bob inside Acme: full name, role, strong areas (becomes Bob's expertise weighting later), and Slack handle for future notification routing.
3. Writes brain/people/bob-smith.md with frontmatter that maps Bob's git identity to his canonical person page (git_authors array).
4. Commits + pushes the new person page (best-effort — if gh / credentials aren't set up, it warns but the file is still on disk and syncs on the next push).
5. Installs the per-company shim — acme.cmd on Windows, acme shell script on macOS / Linux. The shim runs cognition launch acme which cds into the brain repo and execs claude.
6. Registers the brain in ~/.cognition/links.json so cognition list, cognition status, and the shim all know where it lives.

How cognition wire works (engineer flow, cont.)

cognition link only wires the brain repo itself. But engineers work in their actual code repos — acme-api, acme-frontend. So:

$ cognition wire ~/code/acme-api

  cognition wire · enable brain capture inside another repo

  brain:  acme (/Users/bob/code/acme-company-brain)
  target: /Users/bob/code/acme-api

  ✓ .claude/settings.json
  ✓ .mcp.json
  ✓ registered in ~/.cognition/links.json
  ✓ updated brain/people/bob-smith.md (committed + pushed)

  wired. any CC session inside this repo will log activity to the acme brain.

What this does:

1. Writes .claude/settings.json and .mcp.json in the target repo so CC's Stop hook fires + the cognition MCP server is available.
2. Adds the target path to wired_repos in ~/.cognition/links.json. The Stop hook uses this to walk up from any cwd to find the brain.
3. Updates the engineer's person page in the brain with the new wired repo, commits + pushes it (best-effort).

Linked to multiple brains? wire prompts you to pick which one.

Everyday commands

<slug>                  per-company shim — enter that brain, run claude
                        (e.g. `acme`, `stylr`, `globex`)

cognition list          show all brains linked locally + the default
cognition status        "which brain am I in right now?" (cwd-aware)
cognition launch <slug> same as the shim — explicit form for scripts
cognition wire <repo>   enable brain capture inside another code repo
cognition unlink <slug> remove the shim + registry entry (keeps the clone)

The separation matters. Type claude → personal session, no company context. Type acme → Acme's brain loads, your CC session lives inside the company repo, every action gets logged to brain/activity/<you>/, any skills you capture land in brain/skills/. The tooling makes the wrong thing impossible without enforcing a rule.

Page format

---
title: Stripe
owner: vedan
tags: [billing, payments]
pinned: true
---

We use Stripe for subscription billing. Webhook endpoint at
`/api/stripe/webhook`. Test keys in Vercel preview env, live keys in
production. Invoices reconciled nightly via /api/cron/stripe-sync.

Frontmatter is optional. title overrides the slug. pinned: true floats the page to the top of its grid.

Adding pages later

Two ways:

# 1. Let Claude do it
cd your-company-brain
claude "Ingest the README and top-level files of <some-repo> into brain/."

# 2. By hand
echo "..." > brain/services/redis.md
git add -A && git commit -m "add redis" && git push
# Vercel auto-rebuilds

Requirements

• Required: Node 20+, Claude Code
• Optional but recommended: gh for GitHub push, vercel for deploy

cognition init warns you if any are missing. The local scaffold + ingest works without gh/vercel — you just push and deploy manually.

Architecture

   ┌── CEO machine ──┐   ┌── engineer machine ──┐   ┌── another engineer ──┐
   │                 │   │                      │   │                      │
   │  cognition init │   │  cognition link      │   │  cognition link      │
   │       │         │   │  cognition wire api  │   │  cognition wire web  │
   │       ▼         │   │      │               │   │      │               │
   │  ┌──────────┐   │   │      ▼               │   │      ▼               │
   │  │ brain    │◀──┼───┼──▶  ~/code/acme-api  │   │  ~/code/acme-frontend│
   │  │ repo     │   │   │   ↳ stop hook writes │   │   ↳ stop hook writes │
   │  │ brain/   │   │   │     activity to brain│   │     activity to brain│
   │  │  ├ skills│   │   │      │               │   │      │               │
   │  │  ├ people│   │   │   git push           │   │   git push           │
   │  │  └ activ.│   │   └──────┼───────────────┘   └──────┼───────────────┘
   │  └──────────┘   │          │                          │
   └──────┬──────────┘          │                          │
          │                     └──────────┬───────────────┘
          │                                ▼
          └─────────────────────► GitHub brain repo
                                          │
                                   Vercel rebuilds
                                          │
                                          ▼
                                  your-brain.vercel.app
                                  (static site, no backend)

The brain repo is the only shared substrate. The CEO opens the Vercel wiki — sees brain/activity/alice/, brain/activity/bob/, etc. populating with each engineer's CC sessions. Skills land in brain/skills/ and get suggested by the MCP server in future sessions.

Both flows install a per-company shim (<slug> on PATH) plus a registry entry in ~/.cognition/links.json. The registry holds repo paths, remote URLs, and wired_repos — no secrets, no tokens.

No phone-home. No external server. No accounts. The CLI is just scaffold

• primer + shims + hooks; once it runs, you own everything.

Customizing

| What | Where | | ----------------------- | ------------------------------------------------ | | Theme (colors, fonts) | src/app/theme.css | | Layout (tabs, grid) | src/app/BrainView.tsx | | Brain reader logic | src/lib/brain.ts | | Page format | gray-matter frontmatter — anything goes | | New tab type | mkdir brain/<new-kind>/ + add .md files | | Shim install location | %APPDATA%\npm\ (Win), ~/.local/bin/ (POSIX) | | Linked-brain registry | ~/.cognition/links.json (no secrets) |

License

MIT. Fork it, host it, white-label it. Do whatever.

Related

• Claude Code — the CLI that does the ingest and the deploy
• Next.js — the wiki framework
• gray-matter — frontmatter parsing
• marked — markdown → HTML