How BrainThread works

What BrainThread does

BrainThread maintains readable project context beside your code. It derives a briefing from repository files and Git activity, then gives coding agents instructions to read it.

It can observe files, declarations, imports, dependencies and recent changes, and extract documented purpose and constraints. It does not infer your reasons, run your tests or generate answers to coding tasks.

Install

On a supported setup, open a terminal in your Git repository:

npx brainthread init

Setup is staged for your next normal Git commit. Review it with git diff --cached, then keep working. Run init in each repository or clone where you want automatic updates.

What gets created

.brainthread/current.md

The generated briefing: project purpose, observed architecture, recent meaningful changes and documented constraints. It describes a Git snapshot, not uncommitted work.

.brainthread/decisions.md

Decisions you explicitly record. Kept separately so they survive the recent-change window.

.brainthread/config.json, .brainthread/.gitattributes and .brainthread/history/

Configuration, merge settings, change events and a receipt used to check freshness and integrity.

AGENTS.md and CLAUDE.md

A marked BrainThread block tells agents to read the context and decisions. Existing instructions are preserved.

A local runtime and managed hooks live in Git’s private BrainThread directory (normally .git/brainthread/). Init sets the repository’s core.hooksPath and forwards existing executable hooks. This local installation is not transferred by a push.

How updates work

1. You make a normal Git commit or merge.
2. A local post-commit or post-merge hook inspects the committed source snapshot.
3. When the analyzed source changes, BrainThread writes generated context in a separate context-only commit. Your source commit is not amended.

“Meaningful” is determined by file comparison, not a model’s judgment. Generated files, lockfiles and recognized private paths are excluded; canonicalized text avoids some formatting-only changes. The briefing shows up to six recent meaningful events.

For example, changing a task function can produce an observation about the changed file and declaration. Why you chose its default belongs in a recorded decision.

Updates do not watch every keystroke. Context travels with your normal Git pushes. If an update fails, your source commit remains; use doctor and repair. Avoid hand-editing generated context.

Decisions

Record the choice and its reason yourself:

npx brainthread decision "Tasks default to normal priority to preserve existing behavior."

This appends to .brainthread/decisions.md and stages the decision for your next commit. Decisions are not automatically inferred from code or conversations. Each command accepts up to 2,000 characters.

Using it with AI agents

Claude Code and Codex receive repository instructions to read both context files, follow relevant source links and verify disagreements against source. Your agent interprets that context and performs the coding task using its own model.

For another compatible agent, point it to the files directly:

Read .brainthread/current.md and .brainthread/decisions.md.
Check relevant source files before making changes.

BrainThread does not launch or configure a model, and cannot guarantee that an agent follows instructions. An AGENTS.override.md can take precedence over AGENTS.md; doctor reports when the context pointer needs attention.

Commands

npx brainthread init

Install and stage repository setup.

npx brainthread doctor

Check automatic updates, context freshness and agent instructions. Add --verbose for details. It does not run application tests.

npx brainthread context

Print the current briefing and durable decisions.

npx brainthread decision "Decision and reason"

Record and stage an explicit decision.

npx brainthread repair

Restore integration and regenerate memory from Git, preserving decisions. Keeps a bounded recovery backup locally; may create a context commit and stage restored setup.

npx brainthread uninstall

Remove the local integration while keeping saved context.

Privacy / local behavior

The BrainThread runtime runs locally, with no account, API key, model, hosted service or telemetry. It makes no network requests; missing Git objects produce an error instead of a download.

npm needs network access to download the package. Your AI agent, model, Git commands and existing hooks have their own network behavior. The installed hook uses its local runtime, not the npm cache.

Context is stored in your repository and shared when you push it. Recognized secret paths are excluded from analysis, but this is not a comprehensive secret scanner; review generated context before sharing.

The legacy projectbrain and pb compatibility commands retain separate behavior, including explicitly enabled external providers. The runtime claims here apply to brainthread.

Requirements

• macOS. Linux and Windows are not supported or verified for this beta.
• Node.js 22.23.2 or newer; Git 2.39.5 or newer.
• An existing Git repository with the required Git objects available locally.
• Up to 5,000 tracked files and an 8 MiB analysis budget. Individual files over 128 KiB, binary files and symlink contents are not read as text.

If a limit is exceeded, memory is not updated. Use doctor to inspect the installation and any reported errors.

Uninstall

npx brainthread uninstall

Turns off automatic updates and removes the managed integration where it can do so safely. Preserves your own instructions, hooks, work and saved context in .brainthread/. Anything it cannot safely remove is reported.

Existing context commits stay in Git history.