# multi-brain

`multi-brain` is a Rust daemon, CLI, and MCP server for keeping AI-agent
harnesses alive and letting them discover, spawn, inspect, and message each
other without interactive prompts.

The first supported harness kinds mirror the earlier `cc-tg` and `cc-agent`
patterns:

- `claude`: starts Claude Code with stream-json input/output and a saved
  personality injected as the system prompt.
- `codex`: starts Codex through `codex exec ... --full-auto`.
- `open-claw` and `generic`: line-oriented command harnesses for other agent
  CLIs.

## Install

```sh
cargo install multi-brain
```

## Run

Start the global bus headlessly:

```sh
multi-brain start
```

`multi-brain daemon` runs the same daemon in the foreground. Ordinary CLI and
MCP calls auto-start the daemon when it is not already running.

Register and spawn a personality:

```sh
multi-brain register \
  --name reviewer \
  --kind claude \
  --command claude \
  --cwd "$PWD" \
  --personality "You are a strict Rust reviewer locked to this repository."

multi-brain spawn reviewer
multi-brain list
multi-brain ask codex-main reviewer "What risks do you see in this patch?"
multi-brain events reviewer --max 50
```

Expose the registry to an agent as MCP:

```sh
multi-brain mcp
```

The MCP server exposes `list_brains`, `register_brain`, `spawn_brain`,
`ensure_brain`, `ask_brain`, `brain_events`, `inject_multi_brain_mcp`, and
`stop_brain`.

Inject that MCP server into a repository:

```sh
multi-brain inject-mcp --cwd "$PWD" --server-name multi-brain
```

The generated `.mcp.json` points back at this daemon through
`MULTI_BRAIN_HOME`, so harnesses spawned inside that repo can discover and talk
to the same global registry.

## Logs and Transparency

Daemon logs are written to `<MULTI_BRAIN_HOME>/logs/daemon.log` when started
headlessly.

Each harness has a structured JSONL event log:

```text
<MULTI_BRAIN_HOME>/logs/<harness>.jsonl
```

Events include:

- `stdin`: prompts sent from another brain or tool call.
- `stdout`: line output from the harness process.
- `stderr`: line output from the harness process.
- `status`: lifecycle and read-error events.

The same event stream is available through CLI (`multi-brain events`) and MCP
(`brain_events`).

## Storage

By default state lives in the platform data directory. Set
`MULTI_BRAIN_HOME=/path/to/dir` or pass `--home` to isolate a registry.

## Publishing

The crate has Cargo package metadata and is intended to publish as
`multi-brain`.

```sh
cargo publish --dry-run
```

## Test and Coverage

```sh
cargo test
rustfmt --check --edition 2024 src/*.rs tests/*.rs
```

Coverage should be measured with `cargo llvm-cov` or `cargo tarpaulin` in CI.
The current suite covers daemon startup, CLI lifecycle, MCP lifecycle, mock
Claude/Codex harnesses, event logs, and MCP injection.
