Metadata-Version: 2.4
Name: brains-ai
Version: 1.1.1
Summary: Local-first control plane and coordination layer for AI coding agents
Author: mekjr1 and brains contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/mekjr1/brains-v2
Project-URL: Repository, https://github.com/mekjr1/brains-v2
Project-URL: Issues, https://github.com/mekjr1/brains-v2/issues
Keywords: ai-agents,coding-agents,control-plane,openai-compatible,mcp,local-first
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.27
Requires-Dist: websockets>=12
Requires-Dist: pydantic>=2.5
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: typer>=0.12
Requires-Dist: mcp<2,>=1.0
Requires-Dist: jinja2>=3.1
Requires-Dist: starlette>=1.3.1
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Provides-Extra: litellm
Requires-Dist: litellm>=1.40; extra == "litellm"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == "postgres"
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: slack
Requires-Dist: slack_sdk>=3.27; extra == "slack"
Provides-Extra: whatsapp
Requires-Dist: httpx>=0.27; extra == "whatsapp"
Provides-Extra: whatsapp-web
Requires-Dist: httpx>=0.27; extra == "whatsapp-web"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.25; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.25; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == "otel"
Provides-Extra: all
Requires-Dist: litellm>=1.40; extra == "all"
Requires-Dist: asyncpg>=0.29; extra == "all"
Requires-Dist: psycopg[binary]>=3.1; extra == "all"
Requires-Dist: python-telegram-bot>=21.0; extra == "all"
Requires-Dist: slack_sdk>=3.27; extra == "all"
Requires-Dist: opentelemetry-api>=1.25; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.25; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == "all"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == "all"
Dynamic: license-file

<!--
last_verified: 2026-08-06T19:13:03.000-06:00
verified_by: GitHub Copilot CLI
verification_basis: clean-state corrective candidate based on HEAD 96c2b66fe8adddd9ea29f59f2944e8e702453f27; source inspection and regression coverage for first-run SQLite state creation; public package/GHCR/GitHub publication pipeline verified; corrective publication and live deployment not verified
-->

# Brains

Brains is a local-first operator control plane for coordinating AI coding agents across machines, tools, work, and human approvals.

Current maturity: Brains is an alpha release. Core local workflows are covered by blocking CI and sealed local UAT. Live deployment and external provider or bridge behavior depend on operator configuration and are not certified by repository evidence.

Brains is the canonical product and repository identity. It is distributed as `brains-ai`, uses the `brains` Python namespace, `brains_` MCP prefix, `~/.brains` state directory, `brains-spa` frontend package, and Brains browser identity.

## Install

Brains requires Python 3.11 or 3.12. Install the CLI in an isolated environment:

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

Initialize Brains for the project you want it to coordinate, then start the supervised gateway, browser console, and MCP server:

```text
cd <project>
brains-ai setup --path .
brains-ai serve-all
```

Open `http://127.0.0.1:8787/app`. The setup command prints the generated admin-key location; reveal it only when needed with `brains-ai admin-key show --reveal`.

To start Brains automatically at login, use `brains-ai setup --path . --service`. Upgrade an existing isolated installation with `pipx upgrade brains-ai`.

## Canonical documentation

- [Product brief](docs/product/PRODUCT_BRIEF.md)
- [Feature contract](docs/product/FEATURE_CONTRACT.md)
- [User outcome specification](docs/product/USER_OUTCOME_SPEC.md)
- [Personas and journeys](docs/product/PERSONAS_AND_JOURNEYS.md)
- [Traceability](docs/product/TRACEABILITY.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Operations](docs/OPERATIONS.md)
- [Quality gates](docs/QUALITY_GATES.md)
- [Current backlog](docs/product/BACKLOG.md)

## Repository guidance

- [Contributing](CONTRIBUTING.md)
- [Security](SECURITY.md)
- [Agent instructions](AGENTS.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [MIT License](LICENSE)
