claudemesh/docs/vision-20260407.md

claudemesh — Vision & Feature Brainstorm

Date: 2026-04-07 23:01 CEST Author: Alejandro Gutiérrez + Claude (Opus 4.6) Status: Internal brainstorm — not committed to public roadmap Last updated: 2026-04-08 00:09 CEST

---

Tier 1 — High impact, buildable now

1. Session path (pwd) sharing — DONE

Add cwd to the WS hello handshake. Broker stores it in the peer record, list_peers returns it. Peers on the same machine see each other's working directories — lets AI reference files across sessions without guessing paths.

Effort: 30 min. One field in hello + peer list.

Implemented: 2026-04-07 23:30 · 810f372 · CLI 0.6.9 + broker deployed

2. Peer metadata: human vs AI, channel type, model — DONE

Extend the hello handshake with peerType: "ai" | "human" | "connector", channel?: "claude-code" | "telegram" | "slack" | "web", model?: "opus-4" | "sonnet-4" | "gpt-5" | .... Broker stores and broadcasts it. list_peers shows it.

Why: Foundation for connectors, human peers, and smart routing (send complex analysis to the Opus peer, quick tasks to Sonnet).

Effort: 1 hour.

Implemented: 2026-04-07 23:30 · 810f372 · Shipped with item 1 (same commit)

3. System notifications (join/leave/resource events) — DONE

Broker pushes system-level messages when peers connect/disconnect, files get shared, state changes, tasks get created. Same subtype pattern as reminders: { type: "push", subtype: "system", event: "peer_joined", ... }.

Why: Mesh feels alive. AI can react to topology changes without polling.

Effort: 2 hours.

Implemented: 2026-04-07 23:20 · 453705a · peer_joined + peer_left broadcasts, system subtype in push

4. Cron-based reminders — DONE

Replace setTimeout with a persistent cron scheduler (broker-side). AI sends schedule_reminder --cron "0 */2 * * *" --message "check deploy status". Broker uses node-cron or Drizzle-backed scheduler. Survives broker restarts.

Why: Current reminders die if the broker restarts. Cron syntax is already familiar to AI.

Effort: 2 hours (+ DB migration for persistence).

Implemented: 2026-04-07 23:35 · e873807 · DB-persisted schedules, zero-dep cron parser, restart recovery, --cron CLI flag

5. Heartbeats / session supervisor + simulation clock — DONE

Keepalive layer: WebSocket ping/pong for connection health. A CLI-side supervisor monitors the WS connection and relaunches Claude Code if it drops. Broker marks peers as disconnected on WS close.

Simulation clock layer: Heartbeats become a broker-driven clock that peers can subscribe to. The broker broadcasts periodic { subtype: "heartbeat", tick: 42, simTime: "2026-04-08T14:30:00Z", speed: "x10" } messages at a configurable rate.

Time multiplier for load testing:

• mesh_set_clock(speed: "x1") — real-time, normal operation
• mesh_set_clock(speed: "x10") — 1 hour of simulated activity in 6 minutes
• mesh_set_clock(speed: "x100") — 1 day of simulated activity in ~15 minutes

Use case — infrastructure stress testing: Spawn 10 AI peers, each simulating a real user persona (sales rep, admin, customer). Set the clock to x10. Each peer receives heartbeat ticks and acts according to the simulated time: "it's 9am, log in and check dashboard", "it's 11am, process 5 orders", "it's 3pm, run reports". The infrastructure sees realistic usage patterns at 10x speed.

What peers see:

> mesh_clock()
Simulation clock: x10 | sim time: 2026-04-08 14:30 | tick: 42/480

> [heartbeat tick 43 — sim time: 14:36]
  AI peer "Sales-Rep-1": creates 3 orders, searches inventory
  AI peer "Admin-1": approves pending orders, checks stock levels
  AI peer "Customer-1": browses catalog, adds to cart, checks out

Components:

• Broker: clock state + periodic broadcast to all peers
• MCP tools: mesh_set_clock(speed), mesh_clock(), mesh_pause_clock(), mesh_resume_clock()
• Peer behavior: AI reads tick + simTime from heartbeat, decides actions based on its persona and the simulated time of day
• Reporting: broker collects action counts per tick, produces load profile after the run

Why this is powerful: Unlike synthetic load testers (k6, Locust), AI peers exercise the full stack — UI flows, API sequences, edge cases, realistic data entry. They find bugs that scripted tests miss because they improvise like real users.

Effort: 1 day (heartbeat + clock), 1 day (simulation framework + personas).

Implemented: 2026-04-07 · 05d9b56 · Per-mesh clock state, configurable speed x1-x100, auto-pause on empty mesh, heartbeat ticks via system push

---

Tier 2 — Strong ideas, needs design

6. Mesh webhooks / REST API / external WebSocket — PARTIAL (webhooks done)

Three surfaces for external integration:

• Inbound webhooks: POST https://ic.claudemesh.com/hook/<mesh-id>/<secret> → broker injects as a push to all peers or a specific group. GitHub, CI/CD, monitoring alerts become mesh messages.
• REST API: Authenticated endpoints to send messages, read state, list peers from outside. Makes the mesh programmable from any language.
• External WS: Non-Claude clients connect via WS with an API key (not a session keypair). Same protocol, different auth.

Prerequisite: API keys per mesh (not ephemeral session keypairs).

Effort: Half day (webhooks alone), 2-3 days (full API surface).

Partial: 2026-04-07 · b55cf26 · Inbound webhooks implemented (POST /hook/:meshId/:secret → push to mesh). REST API and external WS remain.

7. Connectors: Slack, Telegram as peers — DONE

Approach 1 — Connector-as-peer (recommended start): A bridge process joins the mesh as a peer named "Slack-#general" and relays messages bidirectionally. Peers see it in list_peers with peerType: "connector". One connector per channel.

Approach 2 — Connector-as-router: Broker-level integration — messages to #slack:general route through a registered connector. More elegant, but complex.

Ship as claudemesh-connector-slack, claudemesh-connector-telegram.

Effort: 1-2 days each.

Implemented: 2026-04-07 · Slack: 5563f90 (Socket Mode, echo prevention, auto-reconnect) · Telegram: fe92853 (zero-dep Bot API, long polling)

8. Humans in the mesh

Humans connect via the web dashboard or mobile app using the same WS protocol. peerType: "human" metadata tells AI to adjust communication style. The push system works natively in browsers (WS is bidirectional).

Challenge: UX. Humans need a chat interface with typing indicators, read receipts, message history — not raw JSON. The dashboard already exists at claudemesh.com; extend it with a chat panel.

Effort: 2-3 days (web chat panel).

9. Connecting non-Claude-Code AI — DONE

Any process that speaks the WS protocol can join. The barrier isn't the protocol — it's the MCP tool surface that makes Claude Code sessions first-class. For other LLMs:

• SDK approach: npm install claudemesh-sdk — a JS/Python library that handles WS connection, crypto, and message parsing. Wrap any LLM's function-calling interface around it.
• Push delivery: The push system works over WS. Non-Claude clients receive pushes the same way. The challenge is injecting them into the LLM's context — each platform has a different mechanism (OpenAI function results, Gemini tool responses, etc.).
• Adapter pattern: claudemesh-adapter-openai, claudemesh-adapter-cursor, etc.

Effort: 1 day (SDK), 1 day per adapter.

Implemented: 2026-04-07 · 7e102a2 · @claudemesh/sdk — standalone TypeScript SDK with libsodium crypto_box, EventEmitter API, auto-reconnect

10. Mesh skills catalog — DONE

Peers publish skills: share_skill({ name: "pdf-generation", description: "...", instructions: "..." }). Other peers list_skills() and get_skill("pdf-generation") to load instructions into their context. Broker stores skills like memory/state.

Why: A mesh becomes a capability marketplace. One session installs a skill, all peers benefit. Skills can include tool definitions, system prompts, reference docs, and example workflows.

This is the killer feature. It turns claudemesh from a messaging layer into a knowledge-sharing platform.

Effort: 1 day.

Implemented: 2026-04-07 · c8cb1e3 · Full CRUD (share/get/list/remove), upsert by name, ILIKE search, Drizzle schema

11. Shared project files across peers — DONE

When a peer connects, it registers accessible paths (opt-in per directory). Other peers request files: get_peer_file(peer: "Alice", path: "src/auth.ts"). The owning peer reads the file and returns it over the mesh.

Security scoping options:

• Opt-in per directory: claudemesh launch --share-dir ./src
• Same-machine only (detect via hostname/IP)
• Approval per request

Effort: 1 day.

Implemented: 2026-04-07 · 504111c · Broker relay (never reads content), CLI file serving with 1MB cap, path traversal rejection, hidden files excluded, 2-level dir listing. Plus hostname-based local/remote detection (2c9c8c7) and filesystem shortcut hint (a92cf6b).

12. Peer stats (context consumption, token usage) — DONE

Peers self-report: set_status extended with contextUsed: 85000, contextMax: 200000, tokensIn: 12000, tokensOut: 8000. Dashboard shows burn rate. Useful for load balancing — route work to the peer with the most context headroom.

Limitation: Claude Code doesn't expose context usage via API. Would need estimation from conversation length or /cost command parsing.

Effort: Half day (reporting infrastructure), unknown (accurate context measurement).

Implemented: 2026-04-07 · b3b9972 · Auto-reporting every 60s (messagesIn/Out, toolCalls, uptime, errors), mesh_stats MCP tool, stats in list_peers

---

Tier 3 — Big bets, needs careful thought

13. Mesh blockchain / signed audit log — DONE (audit log)

Honest assessment: A full blockchain is overkill for a cooperative mesh. What's actually valuable is the useful parts:

• Signed append-only log: Immutable record of all decisions, state changes, and messages. Merkle tree integrity. Useful for compliance, debugging, and "who decided what."
• Conflict resolution: Vector clocks or CRDTs for state, instead of last-write-wins.
• Reputation: Track which peers deliver on tasks, respond promptly, produce quality work.

Reframe as: Signed audit trail with integrity proofs. Not a blockchain, but the valuable properties of one.

Effort: 3-5 days.

Implemented: 2026-04-07 · 86a2583 · SHA-256 hash chain audit log, append-only, no message content logged, chain verification endpoint, paginated query

14. Mesh of meshes / bridge

A meta-broker that routes between meshes. Use case: dev-team mesh and ops-team mesh coordinate on deploys.

Simple version: A bridge peer joins both meshes and relays tagged messages. No broker changes needed. Already feasible with today's protocol.

Federation version: Broker-to-broker peering protocol. Brokers exchange presence and route ciphertext across organizations.

Effort: 1 day (bridge peer), 1-2 weeks (federation protocol).

15. Mesh templates on creation — DONE

Predefined mesh configurations: roles, groups, state keys, system prompts, skills, and governance rules. Examples:

• dev-team: @frontend, @backend, @devops groups; lead/member roles; state keys for sprint/deploy-frozen
• research: @analysis, @writing groups; shared memory focus; context-sharing optimized
• ops-incident: @oncall, @comms groups; high-urgency defaults; auto-escalation rules

Templates are JSON files. claudemesh create --template dev-team applies them at mesh creation. Templates are editable post-creation by mesh admin (or anyone, depending on governance).

Effort: Half day.

Implemented: 2026-04-07 · 69e93d4 · 5 templates (dev-team, research, ops-incident, simulation, personal) + claudemesh create command

16. Default private mesh per user — DONE

On claudemesh install, auto-create a personal mesh with the user as sole member. All their Claude Code sessions join by default. Zero-config — instant value without understanding meshes.

Effort: Half day.

Implemented: 2026-04-07 · b0dc538 · Install detects empty meshes, shows join guidance. Local-only mesh deferred (requires broker enrollment).

17. Mesh MCP proxy (dynamic tools without session restart) — DONE

Problem: Claude Code loads MCP servers at startup. You can't inject new tool definitions into a running session.

Solution: Route through the existing claudemesh MCP connection. A generic mesh_tool_call tool proxies to MCP servers registered in the mesh at runtime — no restart needed.

Flow:

1. A peer registers an MCP server: mesh_mcp_register(name: "github", transport: "stdio", command: "npx @github/mcp")
2. Broker stores the registration
3. Any peer calls mesh_tool_call(server: "github", tool: "list_repos", args: {...})
4. Broker routes to the hosting peer or a shared sidecar process
5. That host invokes the actual MCP server, returns the result through the mesh
6. Calling peer gets the response — all through the existing claudemesh WS connection

Two hosting models:

• Peer-hosted: The registering peer runs the MCP server locally. Other peers proxy through them. If that peer disconnects, the MCP goes offline.
• Broker-hosted: The broker spawns the MCP server as a sidecar. Always available. Better for shared tools (database, GitHub, Jira).

What AI sees:

> mesh_mcp_list()
Available mesh MCP servers:
- github (hosted by: Alice) — tools: list_repos, create_issue, ...
- jira (hosted by: broker) — tools: search_issues, create_ticket, ...
- postgres-prod (hosted by: broker) — tools: query, execute

> mesh_tool_call(server: "github", tool: "create_issue", args: {repo: "...", title: "..."})
Issue #42 created.

Limitation: Claude Code won't see these as first-class tools in its tool list — AI needs to know to use mesh_tool_call. MCP server instructions document the proxy pattern.

New MCP tools needed: mesh_mcp_register, mesh_mcp_list, mesh_tool_call, mesh_mcp_remove

Effort: 2-3 days.

Implemented: 2026-04-07 · 08e289a · Full round-trip: register → list → call → forward → execute → result. In-memory registry, 30s call timeout, auto-cleanup on disconnect.

18. Sandbox for code execution

Each mesh gets optional compute sandboxes (Docker containers, Firecracker VMs, or E2B-style). Peers request: execute_code(lang: "python", code: "..."). Broker provisions a sandbox, runs the code, returns stdout/stderr. Resources scale on demand as peers need sandboxes.

Build vs integrate:

• Build: Docker-in-Docker on the broker host. Simple but security-sensitive.
• Integrate: E2B, Modal, or Fly Machines as the sandbox backend. claudemesh MCP tool is a thin client. Scales naturally.

Effort: 2-3 days (E2B integration), 1-2 weeks (self-hosted sandboxes).

19. Mesh dashboard (real-time situational awareness) — DONE

Live web UI at claudemesh.com/dashboard showing:

• Peer graph: Who's connected, status, groups, roles — nodes and edges
• Message flow: Animated edges showing real-time traffic between peers
• State/memory timeline: When values changed and who changed them
• Resource panel: Files shared, tasks active, skills available
• Peer detail: Click a peer → see summary, context usage, message history

Broker already tracks everything needed. Dashboard subscribes via WS and renders with D3/React.

Effort: 2-3 days (functional), 1 week (polished).

Implemented: 2026-04-07 · 59332dc peer graph (radial SVG, animated edges, group rings) + 7d432b3 state timeline + resource panel. Peer detail view remains.

20. Peer visibility and spatial topology — DONE (visibility + profiles)

Control which peers can see each other. Instead of a flat mesh where everyone sees everyone, the broker filters list_peers responses and message routing based on visibility rules.

Three visibility models:

• Proximity-based (simulation): Each peer has coordinates (x, y) and a visibility radius. Only peers within range appear in list_peers. set_position(x, y) changes who you can see — spatial fog of war. Combined with the simulation clock, this creates emergent behavior: a "customer" peer walks into a "store zone", suddenly sees "sales rep" peers, initiates interaction.
• Scope-based (organizational): Visibility follows group membership. Peers in @frontend see each other and @leads, but not @backend internals. Org-chart visibility without exposing every department.
• Manual/dynamic: Peers or admins explicitly show/hide. set_visible(false) to go stealth (connected but invisible). Admin can force visibility/invisibility.

Who controls visibility:

• Broker rules — mesh-wide policy set at creation or via template (e.g., "proximity" mode for simulations, "scope" for orgs)
• Peer self-control — set_visible(false) to go stealth, set_position(x, y) to move in proximity mode
• Admin override — mesh admin force-shows or force-hides peers
• Dynamic conditions — broker changes visibility based on state keys, clock ticks, or events

Notifications: Peers receive { subtype: "system", event: "peer_visible" } when a new peer enters their visibility and peer_hidden when one leaves. Different from join/leave — the peer is still connected, just not visible to you.

Peer public profile (outside image): Each peer has a public-facing profile that other peers see — a curated view separate from internal state. Fields: avatar (emoji or URL), title (short role label), bio (one-liner), capabilities (what I can help with). Set via set_profile({ avatar: "🔧", title: "DevOps Lead", bio: "Infrastructure and deploys" }). This is what appears on the peer graph node and in list_peers. Peers choose how they present themselves to the mesh.

MCP tools: set_visible(visible), set_position(x, y), set_profile(profile), get_visible_peers(), set_visibility_mode(mode) (admin only)

Effort: 2-3 days.

Partial: 2026-04-07 · Visibility toggle (set_visible), public profiles (set_profile), hidden peer filtering in list_peers, peer_visible/peer_hidden system events, direct messages still reach hidden peers. Remaining: proximity-based (x,y coordinates), scope-based (group visibility rules).

21. Semantic peer search

In large meshes (50+ peers), scanning list_peers output is noise. A search_peers tool that filters and ranks by multiple dimensions:

• Structured filters: name, group, role, status, peerType, channel, model, cwd
• Free-text search: matches against peer summaries, profile bios, capabilities, and shared skills
• Capability matching: "find a peer that knows about database migrations" searches across profile capabilities + skills catalog + recent summaries
• Ranking: peers with more matching dimensions rank higher; active (idle/working) peers rank above DND/offline

MCP tool: search_peers(query, filters?) — returns a ranked list of matching peers with relevance scores.

Implementation: Broker-side — accepts a search_peers message, runs multi-field matching against the in-memory peer list + skills table. No external search engine needed for <500 peers; for larger meshes, wire into the existing Qdrant vector store (already available via vector_search).

Effort: Half day.

22. Mesh telemetry and debugging

A structured logging system where peers report errors, warnings, and debug info to the broker. Goes beyond the audit log (which tracks events) — this tracks operational health.

What peers report:

• Errors: tool failures, connection drops, unhandled exceptions
• Warnings: high context usage, slow responses, retry patterns
• Debug: decision traces, task reasoning, why a particular approach was chosen
• Performance: response latency per tool call, message round-trip times

Broker storage: Structured logs indexed by mesh, peer, timestamp, severity. Retained for N days (configurable). Queryable via WS messages.

AI self-analysis: Peers query their own logs to identify patterns: "I've hit this error 3 times in the last hour — what's common?" The mesh becomes self-diagnosing. Leads can query team-wide logs: "Which peers are seeing errors in the deploy flow?"

Reporting: Aggregated metrics per peer, per mesh, per time window. Error rates, common failure modes, response time percentiles. Surfaced in the dashboard or via mesh_report(timeframe: "24h").

MCP tools:

• mesh_log(level, message, data?) — report a log entry
• mesh_logs(query?, peer?, level?, last?) — query logs
• mesh_report(timeframe?) — aggregated health report

Effort: 1-2 days.

23. Peer session persistence ("welcome back")

When a peer disconnects, their state is lost (groups, profile, visibility, stats, summary). On reconnect they start blank. Persist peer state so returning peers resume where they left off.

What persists (keyed by meshId + memberId):

• Groups and roles
• Profile (avatar, title, bio, capabilities)
• Visibility setting
• Last summary
• Cumulative stats (messages, tool calls across all sessions)
• Last seen timestamp

What resets: status (always "idle" on connect), WebSocket/presenceId (ephemeral).

Reconnect flow:

1. Peer sends hello with same memberId
2. Broker looks up peer_state table for (meshId, memberId)
3. If found: restore groups, profile, visibility, stats — hello fields take precedence if explicitly set
4. Enriched hello_ack includes restored: true and previous summary
5. System notification: "Welcome back, Alice! Last seen 2h ago. Restored: @frontend:lead, @devops:member"
6. On disconnect: upsert current state to peer_state

Why: AI sessions restart often (context limits, crashes, new tasks). Without persistence, every reconnect requires manual group joins and profile setup. With it, the mesh remembers who you are.

Effort: Half day.

---

Suggested build order

#	Feature	Effort	Unlocks	Status
1	Session path sharing	30 min	File referencing across sessions	DONE 810f372
2	Peer metadata (type/channel/model)	1 hour	Connectors, humans, smart routing	DONE 810f372
3	System notifications	2 hours	Reactive mesh, awareness	DONE 453705a
4	Cron reminders	2 hours	Persistent scheduling	DONE e873807
5	Mesh templates	Half day	Better onboarding	DONE 69e93d4
6	Default personal mesh	Half day	Zero-config start	DONE b0dc538
7	Inbound webhooks	Half day	External integrations	DONE b55cf26
8	Skills catalog	1 day	Knowledge marketplace	DONE c8cb1e3
9	Shared project files	1 day	Cross-session file access	DONE 504111c
10	Slack connector	1-2 days	Reach beyond Claude Code	DONE 5563f90
11	Mesh MCP proxy	2-3 days	Dynamic tools without restart	DONE 08e289a
12	Dashboard (real-time)	2-3 days	Visual situational awareness	DONE 59332dc + 7d432b3
13	Human peers (web chat)	2-3 days	Humans in the loop
14	Simulation clock (heartbeat x1-x100)	2 days	AI-driven load testing	DONE 05d9b56
15	Sandboxes (E2B)	2-3 days	Shared compute
16	Signed audit log	3-5 days	Trust, compliance	DONE 86a2583
17	Bridge / federation	1-2 weeks	Multi-mesh coordination
18	Peer visibility + profiles	2-3 days	Simulation fog-of-war, org scoping	DONE (types.ts/index.ts)
19	Semantic peer search	Half day	Discovery in large meshes
20	Peer stats reporting	Half day	Resource awareness, load balancing	DONE b3b9972
21	SDK (@claudemesh/sdk)	1 day	Non-Claude-Code clients	DONE 7e102a2
22	Telegram connector	1-2 days	Reach beyond Claude Code	DONE fe92853
23	Mesh telemetry + debugging	1-2 days	Self-diagnosing mesh
24	Peer session persistence	Half day	"Welcome back" on reconnect

---

This document captures a brainstorming session. Items are not commitments. Priorities will shift as we build and learn.