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> stop parallel AI coding agents from clobbering each other's files — a file-scope claim refuses the overlap <em>before</em> two agents edit the same file.
</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="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://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 off each other's files.

> **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** before agents collide: `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, status, and checkpoint to another seat">
  </p>

- **Expose a dark seat.** After 30 continuous seconds without the owner's exact waiter, the hub emits one [`dark_seat_alert`](docs/protocol.md) for affected claims or assigned work, including the permanent-arm remedy; it does not release or reassign work automatically.

  <p align="center">
    <img src="docs/assets/feature-dark-seat.png" width="1170" alt="A dark-seat alert naming the missing exact waiter, affected claim, and permanent synapse arm remedy">
  </p>

- **Read the fleet from one cockpit.** [`synapse dashboard`](docs/studio.md) serves the local command centre, exact-status task columns, claims, conflicts, security posture, and an optional durable event feed; the read-only Studio projection adds no new hub authority.

  <p align="center">
    <img src="docs/assets/feature-cockpit.png" width="1280"