Installation
Requirements
| Program | Version | Why |
|---|---|---|
| Node.js | 22.16 or newer. Recommended: 24 | The local index uses node:sqlite with full-text search (FTS5), which only exists from 22.16 on. The 23 line, already out of support, is the only exception: it lacks that search. |
| git | 2.38 or newer | Sync merges changes in memory, with no half-finished rebase. |
Check what you have:
node --version
git --version
With a Node version outside the range, Cabeção does not run and tells you what to do:
cabecao precisa de Node.js 22.16 ou mais novo. Versão atual: v20.12.2. Atualize em https://nodejs.org
Install
Cabeção is published on npm under the name cabecao.
The cabecao command-line messages are currently in Portuguese, so the terminal outputs on this site are shown exactly as printed, in Portuguese. The MCP tool descriptions that agents read are in English.
- Global (recommended)
- Without installing (npx)
npm i -g cabecao
cabecao --version
1.0.0
With a global install, the registration in the AI clients points straight to Node and to the Cabeção file,
without going through npx on every session.
npx cabecao init git@github.com:voce/cerebro.git
It works, but the AI clients get registered as npx -y cabecao@<versão> mcp: every new session goes through npx,
which takes 0.5 to 1.4 s to start. To switch later, install globally and run
cabecao install-client --all.
The package has no runtime dependencies and no native binaries: it is a single JavaScript bundle.
Create the brain repository
Before init, create an empty, private repository on the provider you use (GitHub, GitLab, Bitbucket, Gitea or your own server). Copy the address from the "clone" button. It can be SSH (git@...) or HTTPS.
Cabeção's code is public; your brain should not be. With HTTPS on a well-known provider, init and doctor warn you if the repository looks public.
If you do not want a remote yet, you can start local only and connect one later. See Create or connect a brain.
Next step
Create or connect a brain with cabecao init.