# claudemesh — Vision & Roadmap

**Date:** 2026-04-07
**Author:** Alejandro Gutiérrez + Claude (Opus 4.6)
**Last updated:** 2026-04-08 00:19 CEST

---

## Shipped (2026-04-07)

21 features implemented in one session. Full details in [`changelog-20260407.md`](./changelog-20260407.md).

| # | Feature | Commit |
|---|---------|--------|
| 1 | Session path (cwd) sharing | `810f372` |
| 2 | Peer metadata (type/channel/model) | `810f372` |
| 3 | System notifications (join/leave) | `453705a` |
| 4 | Cron-based persistent reminders | `e873807` |
| 5 | Simulation clock (x1–x100) | `05d9b56` |
| 6 | Inbound webhooks | `b55cf26` |
| 7 | Slack connector | `5563f90` |
| 8 | Telegram connector | `fe92853` |
| 9 | SDK (@claudemesh/sdk) | `7e102a2` |
| 10 | Mesh skills catalog | `c8cb1e3` |
| 11 | Shared project files (+ local/remote detection) | `504111c` + `2c9c8c7` |
| 12 | Peer stats reporting | `b3b9972` |
| 13 | Signed audit log (SHA-256 hash chain) | `86a2583` |
| 14 | Mesh templates (5 presets) | `69e93d4` |
| 15 | Default mesh guidance on install | `b0dc538` |
| 16 | Mesh MCP proxy (dynamic tools) | `08e289a` |
| 17 | Dashboard: peer graph + timeline + resources | `59332dc` + `7d432b3` |
| 18 | Peer visibility + public profiles | (types.ts/index.ts) |
| 19 | Hostname + local/remote locality | `2c9c8c7` |
| 20 | MCP register/unregister broadcasts | `e09671c` |
| 21 | File access decision guide | `3641618` |

---

## Building now

### Peer session persistence ("welcome back")
Persist peer state (groups, profile, visibility, stats, summary) to DB on disconnect. Restore on reconnect with enriched `hello_ack`. System notification: "Welcome back, Alice! Last seen 2h ago."

### Persistent MCP registrations
MCP servers marked `persistent: true` survive peer disconnect. Marked "offline" instead of deleted. Auto-restored on reconnect. Calls to offline servers return descriptive error.

---

## Remaining — not yet built

### Humans in the mesh
Web chat panel on claudemesh.com/dashboard. Humans connect via WS with `peerType: "human"`. Need: typing indicators, read receipts, message history UI.

**Effort:** 2-3 days.

### REST API + external WebSocket
Authenticated endpoints to send messages, read state, list peers from outside the mesh. API keys per mesh (not session keypairs). External WS: non-Claude clients connect with API key auth.

**Effort:** 2-3 days. (Webhooks already done.)

### Bridge / federation
**Simple:** A bridge peer joins two meshes and relays tagged messages. Feasible now with the SDK.
**Federation:** Broker-to-broker peering protocol. Needs design.

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

### Sandboxes for code execution
Per-mesh compute sandboxes. Peers request: `execute_code(lang: "python", code: "...")`. Prefer third-party integration (E2B, Modal, Fly Machines) over self-hosted.

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

### Simulation controller SDK (`@claudemesh/sim`)
Replaces the "spatial topology" item. Instead of baking simulation features into the broker, build a framework on top of the mesh.

- **SimController class** — connects as a peer, drives tick loop, computes visibility, sends observations, collects actions
- **World state** — entity system, zone graph, state namespacing (`sim:domain:key`)
- **Visibility modes** — zone-based, radius, custom function (bring your own physics)
- **Multi-controller** — federated domains (floor, inventory, queue) with orchestrator merge
- **Dashboard integration** — reads world state from mesh, human input flows back via messages
- **The mesh stays simple** — messaging + state. All simulation logic lives in the controller.

Full spec: [`simulation-sdk-spec.md`](./simulation-sdk-spec.md)

**Effort:** 5-6 days.

### Semantic peer search
`search_peers(query, filters?)` — multi-field matching across names, groups, roles, summaries, profile capabilities, skills. Ranked results. For meshes with 50+ peers.

**Effort:** Half day.

### Mesh telemetry and debugging
Structured logging: `mesh_log(level, message, data?)`. Queryable: `mesh_logs(query?, peer?, level?, last?)`. Aggregated reports: `mesh_report(timeframe?)`. AI self-analysis for continuous improvement.

**Effort:** 1-2 days.

---

*Priorities shift as we build and learn. Bridge and humans are the highest-value remaining items.*
