Metadata-Version: 2.4
Name: brains-ai
Version: 1.6.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.13,>=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"
Dynamic: license-file

# Brains

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

Agent tools run in isolation: each has its own process, its own history, and a partial
view of the work. Brains gives them somewhere shared — so two agents can split work
without colliding, a restarted tool can resume real context instead of a transcript, and
you keep the decisions that need a human.

Brains is alpha software for one local operator. Everything runs on your machine against
a local SQLite database. By default there is no account, no telemetry, and no external
service. Optional owner-approved ASK email notifications use your configured SMTP service;
see [setup and consent](docs/OPERATIONS.md#optional-ask-email-notifications).

## Install and run

Brains requires Python 3.11 or 3.12.

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

Initialize a Workspace, connect your agent tools, and run the service:

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

Open `http://127.0.0.1:8787/app`. Keep the generated admin key private.

Wiring edits only the managed entry in each tool's configuration. Your formatting and
unrelated keys are preserved, and `brains-ai unwire` restores the file byte for byte.

New here? Start with the [guide](docs/GUIDE.md).

## What it does

- **Coordination** — Workspaces, durable Sessions, tasks, exclusive claims, handoffs, and
  checkpoints that survive a tool restart
- **Local work assignments** — create an immutable specification, accept it with an
  existing Session, and record an outcome with evidence and revision-fenced attempt history;
  no process launch or checkout management
- **Workspace Work tab** — author assignments and peer deliberations as the human operator,
  inspect evidence, request cancellation, and explicitly advance complete protocol rounds
- **Communication** — durable mailboxes between agent Sessions, proof-bound waiting for
  unread mail, and peer help requests whose answers must carry evidence
- **Knowledge** — recorded findings, scoped and searchable, so they are not re-derived
- **Human authority** — asks and approvals that fail closed where a person is required,
  with optional, default-off email notifications to the configured owner
- **Evidence** — a hash-chained audit log you can recompute, and the decision behind every
  outward effect
- **Operations** — readiness, backup, restore, and rollback over SQLite

Four harnesses are supported: `claude-code`, `copilot-cli`, `codex`, and `opencode`.

Current-main documentation covers 89 MCP tools. This branch also provides ten protected
operator HTTP endpoints for local assignment and peer-deliberation controls in the
existing Workspace Work tab. Human writes use browser-cookie authentication; agents
accept work and submit evidence through CLI/MCP. See the [operator work guide](docs/GUIDE.md#operator-work-in-the-browser).
This is an unreleased local foundation for part of [#42](https://github.com/xibodev/brains-ai/issues/42),
not completion of cross-process events/replay or transport comparison. Remote runners
in [#36](https://github.com/xibodev/brains-ai/issues/36) and specialist workers in
[#38](https://github.com/xibodev/brains-ai/issues/38) remain deferred to
[#37](https://github.com/xibodev/brains-ai/issues/37) planning. The website describes the
pinned 1.5 release and its 74-tool surface.

Model routing, semantic retrieval, and chat bridges are not supported today. The
[product brief](docs/product/PRODUCT_BRIEF.md) distinguishes planned direction from
non-goals and documents retained internal paths without making them supported features.

## Planning and contributions

[GitHub Issues](https://github.com/xibodev/brains-ai/issues) define work outcomes and
acceptance criteria. The [Brains Project](https://github.com/orgs/xibodev/projects/1)
is the sole source for priority, order, and status; these are not duplicated in Markdown
backlogs or external copies. See [Contributing](CONTRIBUTING.md) before starting work.

## Documentation

- [Website and release history](https://xibodev.github.io/brains-ai/) - published release overview
- [Using Brains](docs/GUIDE.md) — the model, and two coordination walkthroughs
- [MCP surface](docs/MCP.md) — the 89 current-main tools agents can call
- [Product brief](docs/product/PRODUCT_BRIEF.md) — what is in scope, and what is not
- [Architecture](docs/ARCHITECTURE.md) — how the pieces fit together
- [Operations](docs/OPERATIONS.md) — running the service, state, and recovery
- [Quality gates](docs/QUALITY_GATES.md) — how Brains is validated

Native service installation, platform-specific Claude recovery, and the Docker-isolated
full gate are release conditions checked per candidate rather than standing guarantees;
see [Operations](docs/OPERATIONS.md) before relying on a background service.

See [Contributing](CONTRIBUTING.md), [Security](SECURITY.md), the
[Code of Conduct](CODE_OF_CONDUCT.md), and the [MIT License](LICENSE).

The website source lives in [`site/`](site/README.md) on `main` and is deployed by
GitHub Actions. See [website maintenance](docs/OPERATIONS.md#website-maintenance)
for release synchronization and deployment checks.
