setup

Documentation

Overview

Package setup connects brain to the agents that will use it.

The engine has never been the hard part of adopting this. The hard part is the nine steps between cloning the repo and an agent actually answering from your vault — install a runtime, pull models, choose a vault, index it, find the right config file for your host, and hand-write JSON full of absolute paths. Every one of those is a place to give up, and none of them is the part worth having.

So this package does the wiring. It finds the MCP hosts installed on the machine and registers brain with each one, preferring the host's own registration command where there is one and merging its config file where there is not.

Why the host's CLI comes first

Claude Code and Codex both ship a command for this. Using it means their config format stays their problem: when they change it, their command changes with it and brain keeps working. Hand-writing another application's config is a standing bet that its format will not move, and that bet is only worth taking when there is no alternative — which is the case for Claude Desktop and Cursor.

Where a file does have to be written, it is read, merged, backed up and then replaced atomically. Someone's other MCP servers are not ours to lose.

Index

• Constants
• func Names(hosts []Host) []string
• type Host
  • func Hosts() []Host
  • func Only(hosts []Host, names []string) (kept []Host, unmatched []string)
• type Outcome
• type Registration
• type Result
  • func Install(s Server, hosts []Host) []Result
  • func Plan(hosts []Host) []Result
• type Server

Constants

const Name = "brain"

Name is what brain calls itself in a host's server list.

Functions

func Names

func Names(hosts []Host) []string

Names lists every host brain knows how to wire, for error messages.

Types

type Host

type Host struct {
	Name string
	// Detect reports whether this host is installed. Presence-based: a command
	// on PATH, or a config directory that exists. A host nobody has installed
	// is skipped, never failed — "not installed" is not an error.
	Detect func() bool
	// Where is the config path or command shown in the report.
	Where func() string
	// Register points the host at this server.
	Register func(Server) (Outcome, error)
	// List reports every MCP server this host currently has registered, read
	// back rather than assumed. Nil means this host exposes no way to read
	// that back — not an error, just a question this host cannot answer.
	List func() ([]Registration, error)
}

A Host is one application that can talk to an MCP server.

func Hosts

func Hosts() []Host

Hosts returns every MCP host brain knows how to connect to, in the order they are reported.

The list is deliberately short. Each entry is a promise to keep working as somebody else's application changes, and a host added speculatively is a promise nobody asked for.

func Only

func Only(hosts []Host, names []string) (kept []Host, unmatched []string)

Only keeps the hosts the user named, matched case-insensitively on a prefix so `--host claude-code`, `--host "Claude Code"` and `--host codex` all work. An unmatched name is returned so the caller can say so rather than silently wiring nothing.

type Outcome

type Outcome string

Outcome says what happened to one host.

const (
	// Registered means the host now points at this brain.
	Registered Outcome = "registered"
	// Updated means it already had a brain entry and it was replaced.
	Updated Outcome = "updated"
	// Skipped means the host is not installed here.
	Skipped Outcome = "not installed"
	// Failed means it is installed and something went wrong.
	Failed Outcome = "failed"
	// Pending means the host is installed and would be wired. Only Plan produces
	// it — it is what the user is being asked to approve.
	Pending Outcome = "would wire"
)

type Registration

type Registration struct {
	Name    string
	Command string
}

Registration is one server as a host currently reports it — the name it was given and the command line the host will actually run.

type Result

type Result struct {
	Host    string
	Outcome Outcome
	Where   string // config path or command, for the report
	Err     error
}

A Result is one host's line in the report.

func Install

func Install(s Server, hosts []Host) []Result

Install registers the server with every host that is present.

One host failing does not stop the others: a user with a broken Cursor config still wants Claude wired up, and the report tells them which is which.

func Plan

func Plan(hosts []Host) []Result

Plan reports what Install would do, without doing any of it.

Registering brain with every AI tool on someone's machine is a large action for someone evaluating one integration, and it used to happen with no gate at all — not even --yes. Showing the list first costs one function and turns an imposition into a choice.

It does not distinguish "would register" from "would update": finding that out means reading a config the user has not yet agreed to have touched, and for the CLI-based hosts it means asking their command, which is not free. Pending is the honest answer to "what will happen here".

type Server

type Server struct {
	// Bin is the absolute path to the brain binary. Absolute because a host
	// launches it from a working directory nobody chose.
	Bin  string
	Args []string
	// Env is what the host must set. BRAIN_VAULT belongs here and must be
	// absolute for the same reason Bin is.
	Env map[string]string
}

A Server is the command a host should run to reach this brain.