synapbus/CLAUDE.md

SynapBus

Local-first, MCP-native agent-to-agent messaging service. Single Go binary with embedded storage, semantic search, and a Slack-like Web UI.

Repo: github.com/synapbus/synapbus License: Apache 2.0

Tech Stack

Component	Technology	Notes
Language	Go 1.23+	Single binary, cross-compilation, zero CGO
Database	modernc.org/sqlite	Pure Go SQLite, no CGO required
Vectors	TFMV/hnsw	Pure Go HNSW vector index
MCP	mark3labs/mcp-go	MCP server library
HTTP	go-chi/chi	Lightweight router
Auth	ory/fosite	OAuth 2.1 framework
Web UI	Svelte 5 + Tailwind	Embedded via go:embed
Logging	slog	Structured logging
Attachments	Content-addressable FS	SHA-256 dedup

Critical constraint: ZERO CGO. The binary must cross-compile cleanly for linux/amd64, darwin/arm64.

Directory Structure

synapbus/
├── cmd/synapbus/         # main.go entry point (cobra CLI)
├── internal/
│   ├── auth/             # OAuth 2.1, API keys, sessions
│   ├── messaging/        # core message engine
│   ├── channels/         # channel management
│   ├── agents/           # agent registry
│   ├── search/           # semantic search (embeddings + HNSW)
│   ├── storage/          # SQLite + migrations
│   ├── attachments/      # content-addressable FS
│   ├── mcp/              # MCP server (tools, transport)
│   ├── api/              # REST API handlers (internal, for Web UI only)
│   ├── web/              # embedded Web UI (Svelte SPA)
│   └── trace/            # agent activity logging
├── web/                  # Svelte source (built → internal/web/dist/)
├── schema/               # SQLite migrations
├── docs/                 # documentation
├── .specify/             # speckit specs
└── Makefile

Build & Run

make build          # Build Go binary
make test           # Run all tests
make dev            # Run with hot reload
make web            # Build Svelte SPA
make clean          # Clean build artifacts
make lint           # Run linters

./synapbus serve --port 8080 --data ./data

Environment Variables

Variable	Description	Default
SYNAPBUS_PORT	HTTP server port	8080
SYNAPBUS_DATA_DIR	Data directory (SQLite DB, attachments, vector index)	./data
SYNAPBUS_BASE_URL	Public base URL for OAuth metadata (required for LAN/remote)	auto-detect from Host header
SYNAPBUS_EMBEDDING_PROVIDER	Embedding provider: openai, gemini, ollama	(none)
OPENAI_API_KEY	OpenAI API key for embeddings	(none)
GEMINI_API_KEY	Google Gemini API key for embeddings	(none)
SYNAPBUS_OLLAMA_URL	Ollama server URL	http://localhost:11434
SYNAPBUS_MESSAGE_RETENTION	Message retention period (e.g. 12m, 365d, 0 to disable)	12m

Conventions

• Go standard project layout with internal/ for non-public packages
• Table-driven tests
• Context propagation through all function signatures
• Structured logging via slog
• SQL migrations in schema/ directory, numbered sequentially
• MCP is THE agent interface — REST API is for internal Web UI use only
• Every agent action must be traceable by the human owner
• All storage in a single --data directory (SQLite DB + attachments + vector index)

Architecture Principles

1. Local-first, single binary — no external dependencies at runtime
2. MCP-native — agents interact exclusively through MCP protocol tools
3. Pure Go, zero CGO — all dependencies must be pure Go
4. Multi-tenant with ownership — every agent has a human owner
5. Observable by default — all agent actions traced, searchable, auditable
6. Progressive complexity — basic messaging first, advanced features layered on top

Active Technologies

• Go 1.23+ + ory/fosite (OAuth 2.1), mark3labs/mcp-go (MCP server), go-chi/chi (HTTP), Svelte 5 + Tailwind (Web UI) (002-mcp-auth-ux-polish)
• modernc.org/sqlite (pure Go), TFMV/hnsw (vectors) (002-mcp-auth-ux-polish)
• Go 1.25+ (from go.mod) + mark3labs/mcp-go (MCP tools), go-chi/chi (HTTP), golang.org/x/time/rate (rate limiting), k8s.io/client-go (K8s Jobs — optional) (003-webhooks-k8s-runner)
• modernc.org/sqlite (pure Go), migration 009_webhooks.sql (003-webhooks-k8s-runner)
• Go 1.25+ (per go.mod) + mark3labs/mcp-go (MCP tools), go-chi/chi (HTTP), spf13/cobra (CLI), modernc.org/sqlite (storage), TFMV/hnsw (vectors) (004-embeddings-retention-inbox)
• SQLite (modernc.org/sqlite, pure Go) — single DB file in --data directory (004-embeddings-retention-inbox)
• Go 1.25+ (per go.mod) + spf13/cobra (CLI), go-chi/chi (HTTP), mark3labs/mcp-go (MCP) (006-admin-cli-docker-fixes)
• modernc.org/sqlite (pure Go, zero CGO) (006-admin-cli-docker-fixes)
• Go 1.25+ (per go.mod) + go-chi/chi (HTTP), mark3labs/mcp-go (MCP), ory/fosite (OAuth), spf13/cobra (CLI), modernc.org/sqlite (storage), TFMV/hnsw (vectors). NEW: coreos/go-oidc/v3 (OIDC), golang.org/x/oauth2 (OAuth client) (007-platform-features-bundle)
• Go 1.25+ (backend), SvelteKit 2 + Svelte 5 (frontend), SvelteKit (website) + go-chi/chi (HTTP), mark3labs/mcp-go (MCP), modernc.org/sqlite (storage), SherClockHolmes/webpush-go (push notifications — NEW) (008-webui-pwa-analytics)
• SQLite (existing DB, 1 new migration for push_subscriptions), localStorage (font size) (008-webui-pwa-analytics)
• Go 1.25+ (backend), Svelte 5 + Tailwind (frontend) + go-chi/chi (HTTP), mark3labs/mcp-go (MCP), modernc.org/sqlite (storage), spf13/cobra (CLI) (009-attachments-threads)
• SQLite (modernc.org/sqlite, pure Go) + content-addressable filesystem (SHA-256) (009-attachments-threads)
• SQLite (modernc.org/sqlite, pure Go) — new migration 013_reactions.sql (010-reactions-workflows)
• Go 1.25+ (SynapBus), Python 3.12 (Searcher agents) + go-chi/chi, mark3labs/mcp-go, ory/fosite (SynapBus); claude-agent-sdk, httpx, psycopg (Searcher) (013-linkedin-approval-workflow)
• SQLite via modernc.org/sqlite (SynapBus); PostgreSQL (Searcher) (013-linkedin-approval-workflow)
• Go 1.25+ (per go.mod) + go-chi/chi (HTTP), mark3labs/mcp-go (MCP), spf13/cobra (CLI), modernc.org/sqlite (storage), k8s.io/client-go (K8s Jobs) (014-reactive-agent-triggers)
• SQLite via modernc.org/sqlite — new migration 015_reactive_triggers.sql (014-reactive-agent-triggers)
• Go 1.25+ (per go.mod), no CGO, cross-compiled for linux/amd64 + darwin/arm64 + mark3labs/mcp-go (MCP tools), go-chi/chi (HTTP), spf13/cobra (CLI), modernc.org/sqlite (storage), golang.org/x/crypto/nacl/secretbox (secret encryption — pure Go, already in ecosystem), existing SherClockHolmes/webpush-go, TFMV/hnsw, ory/fosite (018-dynamic-agent-spawning)
• SQLite via modernc.org/sqlite — five new migrations (021_goals_tasks.sql, 022_agent_proposals.sql, 023_agent_trust_model.sql, 024_secrets.sql, 025_harness_runs_task_id.sql); existing content-addressable attachment store reused for encrypted secret blobs (018-dynamic-agent-spawning)
• Go 1.25+ (per go.mod) + mark3labs/mcp-go (MCP), go-chi/chi (HTTP), spf13/cobra (CLI), modernc.org/sqlite (storage), jmoiron/sqlx (query helpers), cloudflare/tableflip (graceful restart — NEW), gopkg.in/yaml.v3 (config), xeipuuv/gojsonschema (config-schema validation) (019-plugin-system)
• SQLite via modernc.org/sqlite (pure Go, zero CGO). New core table plugin_migrations. Plugin tables namespaced plugin_<name>_*. (019-plugin-system)
• Go 1.25+ (per go.mod) + mark3labs/mcp-go (MCP tools), go-chi/chi (HTTP), modernc.org/sqlite (storage), TFMV/hnsw (vectors via existing search.Service), existing internal/harness package (dispatch seam). No new external dependencies. (020-proactive-memory-dream-worker)
• SQLite via modernc.org/sqlite — one new migration 028_memory_consolidation.sql. Memory pool reuses the existing messages table on memory-flagged channels. (020-proactive-memory-dream-worker)

Recent Changes

• 002-mcp-auth-ux-polish: Added Go 1.23+ + ory/fosite (OAuth 2.1), mark3labs/mcp-go (MCP server), go-chi/chi (HTTP), Svelte 5 + Tailwind (Web UI)