diff --git a/docs/vision-20260407.md b/docs/vision-20260407.md new file mode 100644 index 0000000..3f4f9b3 --- /dev/null +++ b/docs/vision-20260407.md @@ -0,0 +1,290 @@ +# 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-07 23:36 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 + +**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). + +--- + +## Tier 2 — Strong ideas, needs design + +### 6. Mesh webhooks / REST API / external WebSocket + +Three surfaces for external integration: + +- **Inbound webhooks:** `POST https://ic.claudemesh.com/hook//` → 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). + +### 7. Connectors: Slack, Telegram as peers + +**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. + +### 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 + +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. + +### 10. Mesh skills catalog + +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. + +### 11. Shared project files across peers + +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. + +### 12. Peer stats (context consumption, token usage) + +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). + +--- + +## Tier 3 — Big bets, needs careful thought + +### 13. Mesh blockchain / signed 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. + +### 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 23:25 · `69e93d4` · 5 templates (dev-team, research, ops-incident, simulation, personal) + `claudemesh create` command + +### 16. Default private mesh per user + +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. + +### 17. Mesh MCP proxy (dynamic tools without session restart) + +**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. + +### 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) — PARTIAL + +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). + +> **Partial:** 2026-04-07 23:30 · `59332dc` · Peer graph component (radial SVG layout, animated edges, group rings) added to live dashboard page. Remaining: state/memory timeline, resource panel, peer detail view. + +--- + +## 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 | | +| 7 | Inbound webhooks | Half day | External integrations | | +| 8 | Skills catalog | 1 day | Knowledge marketplace | | +| 9 | Shared project files | 1 day | Cross-session file access | | +| 10 | Slack connector | 1-2 days | Reach beyond Claude Code | | +| 11 | Mesh MCP proxy | 2-3 days | Dynamic tools without restart | | +| 12 | Dashboard (real-time) | 2-3 days | Visual situational awareness | **PARTIAL** `59332dc` | +| 13 | Human peers (web chat) | 2-3 days | Humans in the loop | | +| 14 | Simulation clock (heartbeat x1-x100) | 2 days | AI-driven load testing | | +| 15 | Sandboxes (E2B) | 2-3 days | Shared compute | | +| 16 | Signed audit log | 3-5 days | Trust, compliance | | +| 17 | Bridge / federation | 1-2 weeks | Multi-mesh coordination | | + +--- + +*This document captures a brainstorming session. Items are not commitments. Priorities will shift as we build and learn.*