Metadata-Version: 2.4
Name: brains-ai
Version: 1.3.0
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/xibodev/brains-ai
Project-URL: Repository, https://github.com/xibodev/brains-ai
Project-URL: Issues, https://github.com/xibodev/brains-ai/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
Requires-Dist: cryptography>=42
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-31T18:30:00.000-06:00
verified_by: OpenCode
verification_basis: HEAD 35ce5ff1b4a2eb8bce2777ca7e3cff4d7ceece99 plus the worktree contract correction and isolated Docker full quality, packaged browser, and real OpenCode/Claude/Codex mailbox UAT; installed-service recovery and deployment not verified
-->

# Brains

Brains is a local-first operator control plane for coordinating AI coding agents through shared Workspaces, durable work, and human approvals.

Current maturity: Brains is an alpha release. The normal product is the Workspace-first coordination, governance, operations, access/configuration, GitHub-linkage, and local-lookup surface. Withdrawn implementations are not product claims even where containment removal from current source remains open. Live deployment and external provider behavior 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 and install the supervised
user service:

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

The service starts without a terminal window, restarts on failure, and starts again at
login. Verify it with `brains-ai service status`, then 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`.

Use `brains-ai serve-all` only when foreground logs are useful for diagnosis or
development. 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)
- [Backlog registry](docs/product/BACKLOG.md)
- [Active feature backlog](docs/product/ACTIVE_BACKLOG.md)
- [Experimental feature backlog](docs/product/EXPERIMENTAL_BACKLOG.md)

## Repository guidance

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