synapse-channel

<!--
SPDX-License-Identifier: AGPL-3.0-or-later
Commercial license available
© Concepts 1996–2026 Miroslav Šotek. All rights reserved.
© Code 2020–2026 Miroslav Šotek. All rights reserved.
ORCID: 0009-0009-3560-0851
Contact: www.anulum.li | protoscience@anulum.li
mcp-name: io.github.anulum/synapse-channel
SYNAPSE CHANNEL — repository overview
-->

<p align="center">
  <img src="https://raw.githubusercontent.com/anulum/synapse-channel/main/docs/assets/header.png" width="1280" alt="SYNAPSE CHANNEL — local-first multi-agent coordination bus">
</p>

<p align="center">
  <strong>The local-first coordination bus for fleets of AI agents.</strong><br>
  One WebSocket hub is the shared source of truth for presence, file-scope claims, a shared plan, task status, and capabilities — for agents working in one repository or across a whole ecosystem of them.
</p>

<p align="center">
  <em>Flagship example:</em> coordinate parallel AI coding agents through declared file scopes — the hub refuses a second overlapping live claim, while covered provider hooks and the staged Git gate enforce only their documented mutation boundaries.
</p>

<p align="center">
  <a href="https://github.com/anulum/synapse-channel/actions/workflows/ci.yml"><img src="https://github.com/anulum/synapse-channel/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/anulum/synapse-channel/actions/workflows/fuzz.yml"><img src="https://github.com/anulum/synapse-channel/actions/workflows/fuzz.yml/badge.svg" alt="Fuzz"></a>
  <a href="https://github.com/anulum/synapse-channel/actions/workflows/link-check.yml"><img src="https://github.com/anulum/synapse-channel/actions/workflows/link-check.yml/badge.svg" alt="Link check"></a>
  <a href="https://github.com/anulum/synapse-channel/actions/workflows/clients-cockpit.yml"><img src="https://github.com/anulum/synapse-channel/actions/workflows/clients-cockpit.yml/badge.svg" alt="Cockpit CI"></a>
  <a href="https://github.com/anulum/synapse-channel/actions/workflows/codeql.yml"><img src="https://github.com/anulum/synapse-channel/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
  <a href="https://pypi.org/project/synapse-channel/"><img src="https://img.shields.io/pypi/v/synapse-channel" alt="PyPI version"></a>
  <a href="https://pypi.org/project/synapse-channel/"><img src="https://img.shields.io/pypi/dm/synapse-channel" alt="PyPI downloads"></a>
  <a href="https://pepy.tech/project/synapse-channel"><img src="https://static.pepy.tech/badge/synapse-channel" alt="Total downloads"></a>
  <a href="https://github.com/sponsors/anulum"><img src="https://img.shields.io/badge/GitHub-Sponsors-ea4aaa?logo=githubsponsors" alt="Sponsor SYNAPSE CHANNEL on GitHub"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL%20v3-blue.svg" alt="License: AGPL v3"></a>
  <a href="https://www.remanentia.com/synapse/pricing.html"><img src="https://img.shields.io/badge/commercial%20licence-available-0a7d3c" alt="Commercial licence available"></a>
  <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
  <a href="https://codecov.io/gh/anulum/synapse-channel"><img src="https://codecov.io/gh/anulum/synapse-channel/branch/main/graph/badge.svg" alt="Coverage"></a>
  <a href="https://api.reuse.software/info/github.com/anulum/synapse-channel"><img src="https://api.reuse.software/badge/github.com/anulum/synapse-channel" alt="REUSE status"></a>
  <a href="https://www.bestpractices.dev/projects/13565"><img src="https://www.bestpractices.dev/projects/13565/badge" alt="OpenSSF Best Practices: Passing"></a>
  <a href="https://securityscorecards.dev/viewer/?uri=github.com/anulum/synapse-channel"><img src="https://api.securityscorecards.dev/projects/github.com/anulum/synapse-channel/badge" alt="OpenSSF Scorecard"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
  <a href="https://doi.org/10.5281/zenodo.20801559"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.20801559.svg" alt="DOI"></a>
</p>

<p align="center">
  <strong>English</strong> ·
  <a href="docs/readme/README.zh-CN.md">简体中文</a> ·
  <a href="docs/readme/README.es.md">Español</a> ·
  <a href="docs/readme/README.pt-BR.md">Português (Brasil)</a> ·
  <a href="docs/readme/README.ja.md">日本語</a> ·
  <a href="docs/readme/README.ko.md">한국어</a> ·
  <a href="docs/readme/README.de.md">Deutsch</a> ·
  <a href="docs/readme/README.fr.md">Français</a> ·
  <a href="docs/readme/README.sk.md">Slovenčina</a>
</p>

A local-first coordination bus for a fleet of AI agents working in parallel —
within a single repository or spread across a whole ecosystem of them. One
WebSocket hub is the shared source of truth for **presence**, **work claims**,
**chat**, **task status**, and **resource offers**: agents address each other
across projects and share one plan, while file-scope claims keep the agents in any
one repository from receiving overlapping live authority. Documented provider
hooks and the staged Git gate enforce that authority only on their covered
mutation surfaces.

### Watch the presentation

[![SYNAPSE CHANNEL presentation video on YouTube](https://i.ytimg.com/vi/Dlyn7k0M_Xs/hqdefault.jpg)](https://www.youtube.com/watch?v=Dlyn7k0M_Xs)

[Watch the SYNAPSE CHANNEL presentation on YouTube](https://www.youtube.com/watch?v=Dlyn7k0M_Xs) (8 minutes; starts from the beginning).

> **New here?** Read [**Why SYNAPSE CHANNEL**](docs/why-synapse.md) — a
> five-minute read on what it is, what you build on it, how it differs from the
> tools next to it, and why coordination becomes the bottleneck once you run more
> than one agent.

> **Project lineage:** SYNAPSE CHANNEL dates back to **September 2025**.

The bus is transport-light (one dependency, `websockets`), hub-centric by design
(one place owns presence, leases, and history), and runs entirely on the local
machine. Model workers reply on-channel through any OpenAI-compatible endpoint,
including a local Ollama server, with a deterministic rule-based fallback for
offline use.

**Your existing agents plug in without new code.** Any Model Context Protocol
host — Claude Code, Claude Desktop, Cursor — reaches the bus through the bundled
`synapse mcp` server, which exposes send, durable inbox, status, claim, release,
handoff, and task verbs as MCP tools plus the board, agents, and resources as
read-only MCP resources. Agents that speak A2A connect through the Agent Card face instead.
The hub itself stays protocol-agnostic and the core install keeps its single
dependency — the MCP and A2A adapters are optional extras (`pip install
'synapse-channel[mcp]'`). See the [MCP guide](docs/mcp.md).

```bash
python -m pip install synapse-channel && synapse demo
```

<p align="center">
  <a href="https://pypi.org/project/synapse-channel/"><strong>Get the Python package</strong></a>
  &nbsp;·&nbsp;
  <a href="#first-60-seconds">Run the first 60 seconds</a>
  &nbsp;·&nbsp;
  <a href="docs/quickstart.md">Read the quickstart</a>
</p>

## Coordinate. Observe. Govern.

Synapse's daily promise is three explicit loops:

- **Coordinate** declared work and surface collisions: `synapse git-init`, `synapse git-claim`,
  `synapse git-claim-check --staged`, `synapse task`, and `syn ack` turn work
  scope, dependencies, and evidence into shared state instead of side-channel
  notes.
- **Observe** the fleet from durable state: `synapse who`, `synapse state`,
  `synapse dashboard`, `synapse event-query`, and observed peer rows show who is
  present, what is claimed, what changed, and which peer-hub facts are advisory.
- **Govern** risky actions with evidence: policy checks, approvals, release
  receipts, Merkle roots, ACL surfaces, federation, and encryption-key commands
  make operator decisions auditable. Governance surfaces report by default;
  operators decide what blocks a merge, release, or cross-hub action.
- **Protect the durable log at rest** with optional **SQLCipher** page encryption
  for the live hub event store (plus whole-file AES-GCM envelopes for relay
  logs, A2A state, cursors, and archives). See
  [SQLCipher live event store](#sqlcipher-live-event-store-at-rest) below.

## What it does, surface by surface

Seven shipped coordination surfaces, each named by the command or doc that
delivers it today:

- **Claim before edit.** [`synapse git-init`](#git-native-claims) installs claim-aware Git hooks; `synapse git-claim` records an exact worktree, branch, and path scope so an overlapping claim can be refused before files diverge.

  <p align="center">
    <img src="docs/assets/feature-claim-conflict.png" width="809" alt="A live Synapse claim owner and a competing overlapping claim refused before editing begins">
  </p>

- **Block unclaimed native file edits.** [Provider file-edit claim hooks](docs/claim-guard-hooks.md) adapt Claude Code `Edit|Write`, Codex `apply_patch`, Gemini CLI `replace|write_file`, and Kimi `Edit|Write` to one live-claim decision engine.

  <p align="center">
    <img src="docs/assets/feature-edit-denial.png" width="809" alt="A provider edit hook denying a native file edit because the seat holds no matching claim">
  </p>

- **Share the plan.** `synapse task` and [`synapse board`](docs/coordination-model.md) keep task state, dependencies, and ready work on the hub instead of in separate agent notes.

  <p align="center">
    <img src="docs/assets/demo.gif" width="845" alt="A Synapse task board changing a dependent task from blocked to ready after its prerequisite completes">
  </p>

- **Hand work over without an ownership gap.** [Atomic handoff](docs/coordination-model.md#4-hand-off-and-recover) moves the held task, scope, status, and checkpoint to an online recipient without a release-and-reclaim window.

  <p align="center">
    <img src="docs/assets/feature-atomic-handoff.png" width="809" alt="An atomic Synapse handoff moving a held task, scope, sta