Doramagic Project Pack · Human Manual
slm-mesh
Peer-to-peer communication for AI coding agents. 8 MCP tools, full CLI, Python client. Part of the Qualixar research initiative by Varun Pratap Bhardwaj.
Overview and System Architecture
Related topics: MCP Tools, Claude Code Skills, CLI, and Python Client, Multi-Machine Setup, WebSocket Transport, and Agent Integrations, Configuration, Security, Adapters, and Operations
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: MCP Tools, Claude Code Skills, CLI, and Python Client, Multi-Machine Setup, WebSocket Transport, and Agent Integrations, Configuration, Security, Adapters, and Operations
Overview and System Architecture
Purpose and Scope
SLM Mesh is a peer-to-peer communication layer for AI coding agents. It enables multiple AI agent sessions running on the same machine (or across machines on the same LAN) to discover each other, exchange structured messages, share state, coordinate file edits, and react to events in real time. The project is published as the slm-mesh npm package (v1.3.4) and is part of the Qualixar research initiative, powered by SuperLocalMemory. Source: package.json:1-30, README.md:1-30.
The system is intentionally local-first: it binds only to localhost, requires no cloud dependency, performs no telemetry, and exposes its functionality either through a CLI or as a Model Context Protocol (MCP) server that AI agents consume natively. Source: SECURITY.md:1-30, README.md:30-60.
High-Level Architecture
SLM Mesh is organized around three runtime components that share a common local SQLite database, plus two pluggable adapter contracts for extension.
flowchart LR
subgraph AI[AI Agent Hosts]
CC[Claude Code MCP Client]
CU[Cursor MCP Client]
AI2[Aider / Codex / Windsurf]
end
subgraph Node["Node.js process: slm-mesh"]
MCP[MCP Server<br/>8 tools, stdio]
CLI[CLI<br/>Commander.js]
BR[Broker<br/>HTTP + UDS + WS + mDNS]
end
subgraph Local[Local Resources]
DB[(SQLite WAL<br/>peers / messages /<br/>state / locks / events)]
UDS[Unix Domain Socket<br/>push channel]
end
subgraph Net[Network]
WS[WebSocket<br/>remote peers]
BN[mDNS / Bonjour<br/>peer discovery]
end
subgraph Ext[Extensions]
BA[BackendAdapter<br/>SQLite / Redis / ...]
MB[MemoryBridge<br/>SuperLocalMemory]
end
CC --> MCP
CU --> MCP
AI2 --> CLI
MCP --> BR
CLI --> BR
BR <--> DB
BR <--> UDS
BR <--> WS
BR <--> BN
BR -.uses.-> BA
BR -.uses.-> MBThe three internal components are:
| Component | Entry Point | Role |
|---|---|---|
| Broker | src/broker/broker.ts (compiled via tsup entry broker) | Local HTTP + UDS + WebSocket server that owns the SQLite database, performs peer registration, and routes messages, state, locks, and events. Source: tsup.config.ts:1-15, src/config.ts:1-20. |
| MCP Server | src/mcp/server.ts | Stdio-based MCP server that exposes 8 tools to AI agents and forwards calls to the broker over HTTP. Source: src/mcp/server.ts:1-40, README.md:30-80. |
| CLI | src/cli/cli.ts | Commander.js-based user interface for start, stop, status, peers, send, broadcast, state, lock, events, clean, and version. Source: src/cli/cli.ts:1-40, src/cli/format.ts:1-30. |
Mode selection happens in src/index.ts, which inspects process.argv to decide whether to launch the CLI or the MCP server when the package binary is executed directly. Source: src/index.ts:1-40.
Core Data Model and Communication Primitives
The shared domain model is defined in src/types.ts:1-50. Branded ID types (PeerId, MessageId, EventId) and a small set of enums (PeerStatus, MessageType, AgentType, PeerScope, LockAction, StateAction, EventAction) keep the protocol explicit. The persistent schema lives in src/db/schema.ts:1-30, which creates tables for schema_version, peers, and messages (with matching CHECK constraints on agent_type and status).
The mesh supports six communication primitives, as documented in the README feature table (Source: README.md:10-30):
- Peer Discovery — automatic registration and heartbeat; CLI shows
peerswith pid, agent type, git branch, and project path. Source: src/cli/format.ts:1-20. - Direct Messaging — structured messages with delivery/read tracking stored in the
messagestable. Source: src/db/schema.ts:1-30. - Broadcast — one-to-all messages with
to_peer = NULLsemantics. - Shared State — namespaced key-value entries for cross-peer scratchpads.
- File Coordination — advisory file locks with auto-expiry.
- Event Bus — pub/sub for
peer_joined,peer_left,state_changed,file_locked,file_unlocked, and custom events.
Two extension contracts are defined as TypeScript interfaces: src/adapters/backend.ts:1-50 (storage backends such as Redis or PostgreSQL) and src/adapters/memory-bridge.ts:1-30 (integration with external memory systems like SuperLocalMemory).
Process Architecture, Roles, and Lifecycle
The build produces two ESM bundles (index and broker) targeting Node.js 20, with declarations and source maps. Source: tsup.config.ts:1-15, package.json:30-60.
Since v1.3.x the broker can run in three modes, controlled by SLM_MESH_ROLE (Source: CHANGELOG.md:1-40):
broker— hub machine: spawns and owns the local broker.client— peer machine: connects to a remote broker, never spawns one.auto(default) — inferred fromSLM_MESH_HOST:localhost→broker, remote IP →client.
A separate SLM_MESH_IDLE_TIMEOUT (default 60s) lets a hub machine stay alive between sparse peer connections by setting it to 0 to disable idle shutdown. The broker auto-starts on first use and auto-stops when no peers remain. Source: CHANGELOG.md:1-30, README.md:30-50.
Real-time push is delivered over Unix Domain Sockets (sub-100ms), with a WebSocket path for cross-machine peers. The v1.3.3 fix routes remote peers via WebSocket first and only attempts UDS for local peers, avoiding futile socket dials. Source: CHANGELOG.md:1-10, src/mcp/server.ts:1-30.
Configuration and Security Model
Configuration is centralized in src/config.ts (re-exported as createConfig, MeshConfig, VERSION, PRODUCT_NAME, BRANDING). Source: src/config.ts:1-20, src/index.ts:1-15. The CLI injects a bearer token from ~/.slm-mesh/broker.token into every non-exempt request, where /health is the only auth-exempt path. Source: src/cli/cli.ts:1-40.
The security posture (Source: SECURITY.md:1-30) is:
- Localhost-only binding (cannot bind to
0.0.0.0). - Bearer token authentication on all API endpoints except
/health. - No shell injection:
execFileSyncis used with argument arrays. - Input validation: UUID peer IDs, payload size limits, and rate limiting.
- File permissions of
0o600for sensitive files and0o700for directories. - Zero external network calls; no telemetry.
A thin Python client (python/src/slm_mesh/client.py) wraps the broker HTTP API using only the standard library, allowing non-Node agents to participate. Source: python/src/slm_mesh/client.py:1-40.
Development and Quality Standards
The contributing guide mandates TypeScript strict mode, 100% line coverage, files under 800 lines, functions under 50 lines, and zero any types. The project runs 480 tests via Vitest, with separate typecheck, build, test:watch, and test:coverage scripts. Source: CONTRIBUTING.md:1-30, package.json:15-30. The intentional 8-tool MCP surface is a deliberate constraint to limit agent context consumption; new tools are explicitly excluded from contributions. Source: CONTRIBUTING.md:20-30.
See Also
- MCP Server and Tool Surface
- Broker Internals and Routing
- Configuration and Environment Variables
- Security Model
- Python Client
- Backend Adapters
- Memory Bridge
Source: https://github.com/qualixar/slm-mesh / Human Manual
MCP Tools, Claude Code Skills, CLI, and Python Client
Related topics: Overview and System Architecture, Configuration, Security, Adapters, and Operations
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Overview and System Architecture, Configuration, Security, Adapters, and Operations
MCP Tools, Claude Code Skills, CLI, and Python Client
SLM Mesh exposes a single mesh networking capability through three coordinated surfaces: an 8-tool MCP surface for AI coding agents, a terminal CLI for humans and scripts, and a Python client for Python-based workflows. On top of the MCP surface, Claude Code Skills (/mesh-* slash commands) provide one-keystroke shortcuts. All three surfaces talk to the same local broker via HTTP with bearer-token authentication. Source: README.md.
Entry Point and Mode Detection
A single executable, slm-mesh, decides at runtime whether to act as a CLI or as an MCP server. Source: src/index.ts:16-18. The detection rule is simple: if any argv token after the script name matches a known command (start, stop, status, peers, send, broadcast, state, lock, events, version, clean, help, --help, -h, --version, -V, --json), CLI mode is launched via Commander; otherwise MCP server mode is launched over stdio for Claude Code, Cursor, and other MCP hosts. Source: src/index.ts:9-39. This dual-mode design lets one binary serve both interactive and agent-driven workflows.
The 8 MCP Tools
When launched as an MCP server, the binary registers exactly eight tools, defined in src/mcp/server.ts. According to the project README, the surface is intentionally fixed because each tool consumes agent context — the contributing guide explicitly rejects "new MCP tools" as a contribution category. Source: CONTRIBUTING.md.
| Tool | Purpose |
|---|---|
mesh_peers | Discover active sessions (scoped to machine, directory, or repo) |
mesh_summary | Publish a description of what this agent is working on |
mesh_send | Send a message to a specific peer or broadcast (to: "all") |
mesh_inbox | Read messages, optionally filtering to unread only |
mesh_state | Read or write shared key-value state (get, set, list, delete) |
mesh_lock | Advisory file locking (lock, unlock, query) with auto-expire |
mesh_events | Read or subscribe to peer_joined, state_changed, etc. |
mesh_status | Broker health, peer count, message statistics |
MCP tool calls are translated into HTTP POSTs to the broker through src/mcp/broker-client.ts, which caches the bearer token read from disk and exempts only /health from auth. Source: src/mcp/broker-client.ts:9-50. A long-running PeerListener pushes inbound messages into the agent's notification stream so the model can react promptly. Source: src/mcp/server.ts:1-30.
Claude Code Skills (Slash Commands)
The v1.1.0 release introduced Claude Code Skills — slash commands that wrap the MCP tools for one-keystroke use inside Claude Code. They are documented in the community release notes and re-export the same backing operations:
/mesh-peers— wrapsmesh_peers/mesh-send <message>— wrapsmesh_send(or broadcast)/mesh-lock <file>— wrapsmesh_lock(lock, unlock, or query)/mesh-status— wrapsmesh_status/mesh-sync— a composite dashboard combiningmesh_peers,mesh_inbox, andmesh_status
These skills follow the MCP-first principle: they are thin command aliases, not new wire-protocol features. Companion integration guides ship a .cursorrules file for Cursor and a .windsurfrules file for Windsurf so non-Claude agents also learn to call the same tools proactively. Source: integrations/cursor/README.md:1-30.
Command-Line Interface
The CLI is a thin operator over the same broker HTTP API. Source: src/cli/cli.ts:1-20. It authenticates with the bearer token from ~/.slm-mesh/broker.token, exempting only /health, and renders responses as fixed-width tables via src/cli/format.ts. Output formatters exist for peers, messages, locks, events, and broker status, each handling empty results gracefully ("No messages", "No active locks"). Source: src/cli/format.ts:1-50.
The full command set mirrors the broker endpoints — start, stop, status, peers, send, broadcast, state, lock, events, version, clean — and supports --json output for scripting. A readPidFile/isProcessAlive check ensures the CLI does not double-start the broker; port discovery is delegated to src/broker/port.ts. Source: src/index.ts:9-13, src/cli/cli.ts:1-30.
Python Client
A zero-dependency Python SDK ships under python/, exposing the broker over stdlib urllib. Source: python/README.md:1-30. The client, defined in python/src/slm_mesh/client.py, mirrors the CLI surface one-to-one:
from slm_mesh import SLMMeshClient
client = SLMMeshClient() # connects to localhost:7899
print(client.health())
client.send(from_peer="agent-a", to_peer="agent-b", payload="hello")
client.state_set(key="current_file", value="main.py", peer_id="agent-a")
lock = client.lock(file_path="src/app.ts", peer_id="agent-a")
events = client.events(types=["message", "lock"], limit=10)
The client raises a typed SLMMeshError(message, status_code, response) on broker failures and reads the bearer token from SLM_MESH_DATA_DIR/broker.token, falling back to ~/.slm-mesh/. Source: python/src/slm_mesh/client.py:1-60. It targets Python 3.10+ and ships with no third-party packages.
Data Flow
flowchart LR
A[AI Agent<br/>Claude Code / Cursor] -->|MCP stdio| B[slm-mesh MCP Server<br/>src/mcp/server.ts]
H[Human / Script] -->|CLI| C[slm-mesh CLI<br/>src/cli/cli.ts]
P[Python Program] -->|HTTP| D[SLMMeshClient<br/>python/src/slm_mesh/client.py]
B -->|HTTP + Bearer| E[Broker]
C -->|HTTP + Bearer| E
D -->|HTTP + Bearer| E
E -->|SQLite| F[(peers, messages,<br/>locks, events)]All three surfaces converge on the same broker, which persists state via the SQLite adapter defined in src/adapters/sqlite-backend.ts.
Common Failure Modes
- Broker not running — CLI/MCP calls fail with a connection error. Start the broker first with
npx slm-mesh startor let the MCP server auto-spawn it viaensureBroker. Source: src/mcp/server.ts:1-15. - Missing bearer token — requests to non-exempt paths are rejected;
/healthalways works. Source: src/mcp/broker-client.ts:9-15. - Stale peers — entries past the heartbeat threshold are marked
staleordeadby the SQLite backend. Source: src/adapters/sqlite-backend.ts:1-80.
See Also
- Architecture
- Configuration
- Security Model
- Troubleshooting
- Python Client Guide
Source: https://github.com/qualixar/slm-mesh / Human Manual
Multi-Machine Setup, WebSocket Transport, and Agent Integrations
Related topics: Overview and System Architecture, Configuration, Security, Adapters, and Operations
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Overview and System Architecture, Configuration, Security, Adapters, and Operations
Multi-Machine Setup, WebSocket Transport, and Agent Integrations
Overview
SLM Mesh began as a single-machine peer-to-peer coordination layer for AI coding agents, with the broker using Unix Domain Sockets (UDS) for sub-100ms local push delivery. The v1.1.0 release — "Skills, Integrations & Demo" — extended that model across machines by introducing a WebSocket push transport, mDNS-based broker discovery, and shared-secret authentication (CHANGELOG.md).
This page documents the three pillars of that cross-machine capability: the multi-machine topology (broker/client role split), the WebSocket transport that replaces UDS for remote peers, and the agent integrations that wire popular MCP clients (Claude Code, Cursor, Windsurf, VS Code) and slash-command skills into the mesh.
Multi-Machine Architecture
Each machine in the mesh plays exactly one of two roles, selected at startup. A hub machine runs the broker and listens for inbound WebSocket connections; a peer machine runs only an MCP client that dials a remote broker. The SLM_MESH_ROLE environment variable (added in v1.3.1) makes the role explicit (broker, client, or auto) (CHANGELOG.md).
The Bonjour library (bonjour ^3.5.1 in package.json) powers mDNS auto-discovery so that brokers advertise themselves on the LAN and remote clients find them without hard-coding IPs (package.json). The AgentType enumeration in the core type system identifies which MCP client the peer represents — values include claude-code, cursor, aider, codex, windsurf, vscode, and unknown (src/types.ts).
flowchart LR
subgraph M4["Hub Machine (role=broker)"]
B[Broker HTTP + WS :7900]
UDS1[UDS peer]
end
subgraph M5["Peer Machine (role=client)"]
C1[MCP Client<br/>Cursor]
C2[MCP Client<br/>Claude Code]
end
C1 -- "WS + Bearer token" --> B
C2 -- "WS + Bearer token" --> B
UDS1 -- "UDS push" --> B
B -. "mDNS advertisement" .- LAN((LAN))
LAN -. "mDNS browse" .-> C1A typical two-machine setup binds the broker with SLM_MESH_HOST=0.0.0.0 and a matching SLM_MESH_SHARED_SECRET, then points the client machine at the broker's IP. Both sides must agree on the secret; the WebSocket server refuses connections without a valid bearer token (README.md).
WebSocket Transport
The remote push path is implemented by two cooperating components defined in the broker and MCP layers.
Broker-side WebSocket server. WsServer is an authenticated WebSocket server that runs alongside the HTTP broker. It accepts upgrades on a configurable port (default 7900), validates a Bearer token against a set of allowed tokens, and maintains a peerId → clientId map so that sendToPeer(peerId, data) can deliver notifications to a specific remote peer (src/broker/push/ws-server.ts). The hasRemotePeer(peerId) predicate is the routing key: the broker uses it to decide whether to attempt a UDS push or a WebSocket push, fixing the bi-directional cross-machine routing bug fixed in v1.3.3 (CHANGELOG.md).
Client-side push client. Each MCP server process owns a WsPushClient that dials the remote broker, performs the hello handshake, and reconnects with exponential backoff on disconnect. The same PeerListener abstraction exposes both UDS (local broker) and WebSocket (remote broker) push channels through a single notification callback, so the MCP tool handlers don't need to know which transport is in use (src/mcp/peer-listener.ts).
The two transports form a WS-first, UDS-fallback routing rule: local peers on the same machine are reached over UDS for minimal latency; remote peers are reached over WebSocket with shared-secret authentication (CHANGELOG.md).
Agent Integrations
MCP Server Configuration
The MCP server (src/mcp/server.ts) exposes eight tools — mesh_peers, mesh_send, mesh_lock, mesh_summary, mesh_state, mesh_events, plus helpers — over the Model Context Protocol. It auto-starts the broker on first use, detects the calling agent by inspecting the process tree, and registers a PeerListener so pushed notifications arrive in real time (src/mcp/server.ts).
Setup snippets from the README cover Claude Code (claude mcp add …), Cursor (.cursor/mcp.json), and any generic MCP client that accepts a command + args pair (README.md). Because transport is automatic, the same MCP configuration works whether the broker is local (UDS) or on another machine (WebSocket).
Slash-Command Skills
The v1.1.0 release added five Claude Code skills — /mesh-peers, /mesh-send, /mesh-lock, /mesh-status, /mesh-sync — that wrap the MCP tools in slash commands so users can coordinate without writing tool calls by hand. The /mesh-send skill, for example, calls mesh_peers to confirm listeners, then broadcasts or direct-sends via mesh_send and reports the returned message IDs (skills/mesh-send.md). Cursor and Windsurf receive equivalent integration guides via .cursorrules and .windsurfrules (CHANGELOG v1.1.0).
Configuration Reference
The cross-machine features are all environment-variable driven. The table below lists the variables documented in the README and changelog that govern transport, discovery, authentication, and role selection.
| Variable | Default | Purpose |
|---|---|---|
SLM_MESH_HOST | 127.0.0.1 | Broker bind address; use 0.0.0.0 for remote access. |
SLM_MESH_WS_PORT | 7900 | WebSocket server port for remote peer push. |
SLM_MESH_SHARED_SECRET | (auto-generated) | Bearer token required on every WS upgrade. |
SLM_MESH_DISCOVERY | true | Enables mDNS advertise/browse on LAN. |
SLM_MESH_ROLE | auto | Explicit broker, client, or auto-detect from HOST. |
SLM_MESH_IDLE_TIMEOUT | 60000 | Broker idle shutdown in ms; 0 disables. |
Common Failure Modes
- Authentication mismatch. If two machines have different
SLM_MESH_SHARED_SECRETvalues, the WebSocket upgrade is rejected silently; symptoms are peers that appear via mDNS but never receive messages. - Firewall on port 7900. mDNS discovery succeeds, but the WebSocket dial times out. Verify the port is reachable between machines (README.md).
- Routing to the wrong transport. Fixed in v1.3.3 — the broker must call
hasRemotePeer(peerId)before attempting a UDS push, otherwise remote peers trigger futile local socket connections (CHANGELOG.md). - Stale peer entries. Peers that crash without a clean disconnect remain visible until the broker's stale-cleanup sweep runs; the
SLM_MESH_IDLE_TIMEOUTcontrols shutdown, while theBackendAdapter.cleanStalePeerssweep removes zombies (src/adapters/backend.ts, CHANGELOG.md).
See Also
- Architecture Overview — Broker, MCP server, and CLI component model
- API Reference — All 8 MCP tools and 12 broker endpoints
- Configuration — Full environment variable reference
- Security Model — Bearer tokens, mDNS scope, threat model
Source: https://github.com/qualixar/slm-mesh / Human Manual
Configuration, Security, Adapters, and Operations
Related topics: Overview and System Architecture, Multi-Machine Setup, WebSocket Transport, and Agent Integrations
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Overview and System Architecture, Multi-Machine Setup, WebSocket Transport, and Agent Integrations
Configuration, Security, Adapters, and Operations
SLM Mesh is a peer-to-peer coordination layer for AI coding agents that runs as three cooperating components: a CLI, an MCP server, and a broker daemon. This page covers the cross-cutting concerns that tie those components together: how the runtime is configured, how it stays secure on a single host, how its storage and memory layers are abstracted through adapters, and how the broker process is managed from start to clean shutdown.
Configuration
The mesh reads its configuration from a single createConfig() factory exported from src/config.ts. The factory is called by every component that needs runtime paths and ports (broker entry, CLI, MCP server), which guarantees that all processes agree on filesystem locations and the listening port. Defaults are environment-aware: data lives under ~/.slm-mesh/ and the HTTP broker listens on 127.0.0.1 only.
The CHANGELOG (CHANGELOG.md) documents the most important environment variables introduced after 1.3.0:
| Variable | Default | Purpose |
|---|---|---|
SLM_MESH_IDLE_TIMEOUT | 60000 (ms) | How long the broker may sit with zero peers before shutting down. Set to 0 to disable idle shutdown entirely — useful for hub machines expecting delayed peer connections. |
SLM_MESH_ROLE | auto | Forces the machine to behave as a broker (spawns local broker), client (connects to remote broker, never spawns), or auto (infers from SLM_MESH_HOST: localhost → broker, remote IP → client). |
SLM_MESH_HOST | 127.0.0.1 | Broker host the client connects to. When set to a non-loopback address, the role is auto-set to client. |
A new role field was also added to MeshConfig so downstream code can branch on broker vs. client behavior without re-parsing environment variables. Source: CHANGELOG.md:18-24
The CLI discovers the running broker's port through discoverPort() in src/broker/port.ts and reads the bearer token from disk via src/broker/token.ts. The buildAuthHeaders() helper in src/cli/cli.ts automatically attaches Authorization: Bearer <token> to every request except /health, which is explicitly exempt for liveness probes.
Security
SLM Mesh is explicitly designed for single-machine, single-user use, and the threat model is enforced at every layer. The full policy is described in SECURITY.md, and the key guarantees are:
- Localhost-only binding — the broker HTTP server cannot bind to
0.0.0.0, preventing accidental LAN exposure. - Bearer token auth — every non-health API endpoint requires a token that is generated on broker startup and persisted to a file with
0o600permissions. Source: src/cli/cli.ts:16-31 - Input validation — peer IDs are validated as UUIDs, payloads have size limits, and the server applies rate limiting before reaching the storage layer.
- No shell injection — subprocess spawning uses
execFileSyncwith argument arrays, never string interpolation. - File permissions — sensitive files are written
0o600; the data directory itself is0o700. - Zero telemetry — no outbound network calls; no usage data leaves the host.
The MCP server in src/mcp/server.ts wraps these guarantees by routing all tool calls through the authenticated broker-client, so even when a hostile agent connects via MCP it cannot bypass the token check or the localhost restriction.
Adapters
The mesh keeps its storage and memory layers behind narrow interfaces so that future contributors can swap implementations (Redis, PostgreSQL, or custom stores) without touching the broker. Two contracts are defined:
BackendAdapter— see src/adapters/backend.ts. It covers the full domain: peer registration and heartbeat updates, message send/get/delivered/read, shared state get/set/list/delete, advisory file lock acquire/release/query, and event recording. The current production adapter is SQLite, but the interface is the only thing callers depend on.MemoryBridge— see src/adapters/memory-bridge.ts. It is an optional integration point for the SuperLocalMemory system: hooks fire on new messages, state changes, and system events, and arecall(query)method returns relevant context strings.isAvailable()lets the broker skip the bridge entirely on hosts where the memory system is not installed.
The domain types referenced by both interfaces are centralized in src/types.ts (Peer, Message, Lock, StateEntry, MeshEvent), which keeps the adapter surface and the SQLite schema in src/db/schema.ts in lock-step.
flowchart LR Agent[AI Agent / MCP Client] -->|MCP tool call| MCP[src/mcp/server.ts] CLI[src/cli/cli.ts] -->|HTTP + Bearer| Broker MCP -->|HTTP + Bearer| Broker[Broker daemon] Broker --> Backend[BackendAdapter] Broker --> Memory[MemoryBridge<br/>optional] Backend --> SQLite[(SQLite WAL)] Memory --> SLM[SuperLocalMemory]
Operations and Lifecycle
Operational behavior is split across four small modules that keep responsibilities tight:
- src/broker/broker-entry.ts — the daemon entry point. It builds a
BrokerfromcreateConfig()and callsstart(); any unhandled error is logged and the process exits with a non-zero code so a supervisor can restart it. - src/broker/pid.ts — reads the PID file and checks
isProcessAlive()to decide whether to spawn a new broker or attach to the existing one. This is the basis of the auto-lifecycle promise in the README ("broker auto-starts on first use, auto-stops when no peers remain"). - src/broker/idle.ts — implements the
SLM_MESH_IDLE_TIMEOUTbehavior. A timer watches the peer count; once it reaches zero the broker waits the configured grace period and then shuts down. With0the timer is disabled, which is the recommended setting for persistent hub machines. - src/broker/cleanup.ts — performs housekeeping: marks peers
stalepast the heartbeat threshold, removesdeadpeers, and expires advisory file locks. A v1.3.3 fix recorded in the CHANGELOG corrected a WebSocket peer routing bug where remote peers connected via WS still triggered futile UDS socket connections — the broker now checkshasRemotePeer()and prefers WS routing with UDS fallback. Source: CHANGELOG.md:3-8
A typical operational flow therefore looks like: CLI / MCP call → ensureBroker checks the PID file → spawn or attach → broker authenticates the request via the token file → adapter writes through to SQLite → idle timer re-evaluates peer count → on 0 peers (and timeout > 0) the broker exits and the PID/token files are removed on next clean.
The release also ships Claude Code skill commands (/mesh-peers, /mesh-send, /mesh-lock, /mesh-status, /mesh-sync) and integration guides for Cursor, Windsurf, and VS Code — these are mentioned in the v1.1.0 release notes and consume the same broker API described above.
See Also
- Architecture and Components — high-level system diagram and component responsibilities
- MCP Tools Reference — the 8-tool surface exposed by
src/mcp/server.ts - CLI Reference — full command list built on
commanderinsrc/cli/cli.ts - Security Model — extended threat model and architectural decisions (linked from SECURITY.md)
Source: https://github.com/qualixar/slm-mesh / Human Manual
Doramagic Pitfall Log
Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
Doramagic Pitfall Log
Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.
1. Configuration risk: Configuration risk requires verification
- Severity: medium
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.host_targets | https://github.com/qualixar/slm-mesh
2. Capability evidence risk: Capability evidence risk requires verification
- Severity: medium
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | https://github.com/qualixar/slm-mesh
3. Maintenance risk: Maintenance risk requires verification
- Severity: medium
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | https://github.com/qualixar/slm-mesh
4. Security or permission risk: Security or permission risk requires verification
- Severity: medium
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | https://github.com/qualixar/slm-mesh
5. Security or permission risk: Security or permission risk requires verification
- Severity: medium
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | https://github.com/qualixar/slm-mesh
6. Maintenance risk: Maintenance risk requires verification
- Severity: low
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | https://github.com/qualixar/slm-mesh
7. Maintenance risk: Maintenance risk requires verification
- Severity: low
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | https://github.com/qualixar/slm-mesh
Source: Doramagic discovery, validation, and Project Pack records
Community Discussion Evidence
These external discussion links are review inputs, not standalone proof that the project is production-ready.
Count of project-level external discussion links exposed on this manual page.
Open the linked issues or discussions before treating the pack as ready for your environment.
Community Discussion Evidence
Doramagic exposes project-level community discussion separately from official documentation. Review these links before using slm-mesh with real data or production workflows.
- v1.1.0 — Skills, Integrations & Demo - github / github_release
- Configuration risk requires verification - GitHub / issue
Source: Project Pack community evidence and pitfall evidence