Your Repo Is Public. Your Thinking Isn't.

An agent can read my code and suggest an approach I ruled out weeks ago. The suggestion may be perfectly reasonable. The code doesn’t explain why we didn’t build something else.

That explanation used to be somewhere in Obsidian, a gitignored note, or an old agent conversation. I could usually find it. Getting it into the next session was another job.

Putting everything in the code repo would help with retrieval, but it would tie two decisions together: what I need to remember and what I’m willing to share. My projects often start privately and get shared later. Rough plans, operational notes, and ideas I might abandon don’t all belong in that public history. Writing an idea down shouldn’t turn it into a promise to build it.

I wanted the reasoning to have a history of its own, accessible to me and the agent. Sharing it could be a separate decision. That’s why I built Dotbrain.

Private doesn’t have to mean hard to reach

The arrangement is fairly ordinary: keep the context outside the code repo, version it separately, and give the project links to it. Dotbrain is the local CLI and plugin for Claude Code and Codex that maintains that arrangement.

Each project gets a private Brainspace. Its Brain holds knowledge in ordinary files: vocabulary, decisions, designs, and runbooks. Its execution store holds issues and dependencies, using Beads. The code repo reaches them through ignored filesystem links, .brain and .beads, rather than containing copies.

In this example, the targets are ~/dotbrain/brainspaces/my-project/.brain and ~/dotbrain/brainspaces/my-project/.beads. I version the knowledge files in the private ~/dotbrain home. A changed decision can have a visible history without becoming part of the code’s history.

The agent workspaces, .claude and .codex, remain real directories in the checkout. Dotbrain adds selected skills and runtime-specific agent definitions without taking over project-owned files. The agent can reach the context from the project tree, but the code repo’s Git ignores that private wiring.

That separation matters when the work moves. A gitignored notes folder is a reasonable place to start. I used some version of one for years. A fresh worktree doesn’t inherit it, though, and a clone on another machine doesn’t bring it along. The code arrives without the explanation.

Wiring a worktree with Dotbrain connects it to the main checkout’s existing Brainspace. Both reach the same knowledge and issue store. Removing the worktree doesn’t leave another set of notes to reconcile.

Another machine is different. I clone the private home and wire the checkout there, but that only brings the Brain’s Git-tracked files. The Beads database needs separate synchronization or backup, through a Dolt remote or shared server. Cloning the home alone doesn’t recover the issues. There are two kinds of state here, and I need to look after both.

Reachable isn’t the same as useful

Giving an agent access to every note isn’t much help if every session has to read all of them.

The plugin’s session-start hook loads the shared Dotbrain convention: where the Brain is, how it’s organized, and what must remain private. The agent reads the project rules and follows the material relevant to its task. It gets a map, not the entire filing cabinet.

The organization matters as much as the links. A design holds current intent. The tracker holds execution state. Vocabulary and durable decisions stay in the Brain after the work ends. I describe how discoveries move between them in A Graph of Tasks, a Loop of Learning.

I can inspect those same files. If an explanation is wrong, I can fix it. If a decision changes, I can record what replaced it. Neither of us has to rely on an agent recalling the right version of an old conversation. Bundled skills and selected project skills make the working practices available too, without assembling them again each time I switch between Claude Code and Codex.

I need the context for myself as well. A useful explanation for an agent doesn’t automatically mean I understand the result well enough to maintain it.

The Brain can become a local reading site with search, navigation, and rendered diagrams. Dotbrain serves it locally; it doesn’t publish the material. The teach-me skill uses the Brain and current code to explain a topic, check understanding, and carry a learning path across sessions. Lessons and records of demonstrated understanding stay private. That’s a different use of the same material: helping me own the change, not just helping the agent make it.

The links don’t decide what leaves

Private storage gives me room to change my mind. I use public issues for intake and keep execution state in Beads. A report may lead through an investigation and several possible designs before there’s a useful answer to share. The person who reported it needs that answer, not necessarily every tentative milestone along the way.

But an ignored link is not a privacy boundary for the words that pass through it. An agent can read a private note and copy it into a public commit message. Separating the files doesn’t prevent that.

The convention therefore covers public output too. Something worth sharing becomes a fresh document written for its audience, rather than a copy of the private source. An investigation might become a troubleshooting guide without exposing the internal runbook or rough plans.

I still have to review it. Dotbrain gives the thinking somewhere private to live; it doesn’t decide what I should make public.

It needs to earn the extra structure

A private repo, ignored links, and a convention can do much of this without Dotbrain. The tool has to make that setup easier to maintain than doing it by hand.

It adds a private home, a plugin and CLI, and Beads when I use it. The Brain needs a private backup, and the tracker needs its own. Moving machines or changing configuration can mean refreshing the wiring. Those costs don’t disappear because the folders are tidy.

If a short AGENTS.md is enough, I’d leave it at that. I find the extra structure worthwhile when the alternative is hunting for old reasoning, copying notes between checkouts, and explaining decisions that should already be available.

What I want is fairly modest: the next session should have a fair chance of starting from what the last one learned. That shouldn’t require making every thought along the way public.

The documentation and source code describe the arrangement in more detail.