Install. Connect. Check the work.

1. Install in an isolated environment

Use Python 3.11 or 3.12. The supported executable and distribution are both named brains-ai. If pipx is not installed, set it up first; open a new terminal after updating your PATH.

python -m pip install --user pipx
python -m pipx ensurepath
pipx install brains-ai

Already using uv? uv tool install brains-ai is an isolated alternative. For a virtual environment or editable source installation, follow the full installation guidance and contributor setup.

Published release: v1.6.0. Run brains-ai version to inspect your own installation; this page is not a probe of your machine.

2. Register your project and connect a tool

In your project's directory, run the commands below. setup --no-wire registers that path as a Workspace and generates an admin key without wiring every detected harness. The next command connects only your selected tool. Keep the key private: never put it in a URL, screenshot, issue or repository.

brains-ai setup --path . --no-wire
brains-ai wire --tool claude-code
brains-ai serve-all

Choose a different tool in Connecting if needed. Keep this terminal running. The foreground supervisor runs the gateway and MCP children; do not start a second stack against the same state or ports.

3. Verify before doing work

Open http://127.0.0.1:8787/app and authenticate using the local console flow. The default Streamable HTTP MCP endpoint is http://127.0.0.1:9877/mcp. Custom service ports may differ; inspect the reported endpoints.

brains-ai readiness
brains-ai wire --status
brains-ai state --workspace .

Readiness reports component results, not just an alive process. Confirm that your Workspace is visible, your harness is wired and the expected listeners respond. Then ask your connected agent to read brains_get_state for this Workspace before editing anything.