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.

---

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

---

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