From dc7e0e826db2c62b1c990d70e4a39b99faa3babe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Guti=C3=A9rrez?= <35082514+alezmad@users.noreply.github.com> Date: Sat, 2 May 2026 18:27:50 +0100 Subject: [PATCH] docs(roadmap): refresh after v1.6.0 ships + add daemon redesign target MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Public docs/roadmap.md gets the v1.6.0 cut moved to shipped, drops the v0.2.0-as-next section in favor of a v1.6.x patch line + v1.7.0 demo cut + v2.0.0 daemon redesign + v3.0.0 native-channels migration target. Items that were in v0.2.0-next migrate down: gateways and tag routing land in v0.3.0 alongside per-topic encryption and self-hosted broker. The detailed strategic version lives at .artifacts/specs/2026-05-02-roadmap.md — schedule, cost estimates, migration paths, deliberate exclusions, the load-bearing principle for the daemon shift ("the user is the unit, not the Claude session"). The public file stays marketing-tone; the artifact captures internal planning. Co-Authored-By: Claude Opus 4.7 (1M context) --- .artifacts/specs/2026-05-02-roadmap.md | 194 +++++++++++++++++++++++++ docs/roadmap.md | 118 ++++++++++++--- 2 files changed, 290 insertions(+), 22 deletions(-) create mode 100644 .artifacts/specs/2026-05-02-roadmap.md diff --git a/.artifacts/specs/2026-05-02-roadmap.md b/.artifacts/specs/2026-05-02-roadmap.md new file mode 100644 index 0000000..edfe01f --- /dev/null +++ b/.artifacts/specs/2026-05-02-roadmap.md @@ -0,0 +1,194 @@ +# claudemesh internal roadmap — 2026-05-02 + +Strategic counterpart to `docs/roadmap.md` (which is the public, marketing-tone roadmap). This file captures the *why*, the dependencies, the costs, and the things we deliberately won't do. + +Anchored in the v0.2.0 backend cut + `#general` auto-creation + filename-tracked migrator + owner-member backfill that all shipped 2026-05-02. + +--- + +## Forcing function + +> **Ship v1.6.x in 2 weeks. Ship v1.7.0 in a month. Make the demo. Then commit the daemon.** + +Each release stands on its own — usable and shippable even if the next slips. That's the property to optimize for, not "fastest path to v3.0.0." + +--- + +## Schedule + +| When | Version | Theme | Status | +|---|---|---|---| +| Now | 1.6.0 | v0.2.0 backend cut | ✅ shipped 2026-05-02 | +| +2w | 1.6.x | Demo polish (SSE, unread, sidebar) | Active | +| +5w | 1.7.0 | First marketing-ready version | Planned | +| +9w | 2.0.0 | Daemon redesign | Planned | +| +15w | 0.3.0 | Self-hosted + per-topic encryption + gateways | Planned | +| TBD | 3.0.0 | Native Claude channels | Anthropic-gated | + +≈4 months from today to a teams-can-self-host shape. The MCP bridge stays load-bearing the whole time but stops being the user's problem at v2.0.0. + +--- + +## v1.6.x patch line — 0-2 weeks, polish what's deployed + +| Item | Effort | Why now | +|---|---|---| +| Real-time push (SSE on `/api/v1/topics/:name/stream`) | 2 days | Chat lag is the only user-visible v0.2.0 wart. Replaces 5s polling. | +| Unread counts via `last_read_at` | ½ day | Schema column already exists. PATCH on scroll-to-bottom + chip on topic list. | +| Bridge end-to-end smoke (two-mesh forwarding test) | ½ day | Feature shipped, never validated. Catches obvious bugs before any external demo. | +| Drizzle journal + `meta/` cleanup | 1 hour | Inert dead files since the new runner. Low-risk cosmetic. | +| `/v1/peers` includes humans (synthetic presence rows for active apikeys) | 1 day | Today the dashboard chat user is invisible to other peers. | + +Total: ~1 week of focused work. Closes the v0.2.0 backend chapter cleanly. + +--- + +## v1.7.0 — 2-3 weeks, the demo cut + +The release that turns claudemesh into a thing you can record and show. + +**Scope:** +- Member sidebar in the chat panel — names, online dots, presence summaries. Comes nearly free with SSE from v1.6.x. +- Topic search + member-mention autocomplete — `@Mou` hot-keys to `claudemesh send Mou ...`. +- Notification feed at `/dashboard` — "you have N unread in #deploys, 2 mentions in #incident." Purely aggregate; no new schema. +- One-line marketing site refresh — capture screenshots from the now-real-time UI, drop the v0.2.0 stamp from the chat footer, update README/landing. +- First public blog post + recorded demo — "claudemesh in 90 seconds" video. Triggers the first proper user-acquisition push. + +**Not in scope:** any architectural change. v1.7.0 is pure UX polish on top of the v1.6.x foundation. Architecture work waits for v2.0.0. + +**Why this comes before v2.0.0:** without users, the daemon is a solution for nobody. v1.7.0 produces the first real user signal so v2.0.0 has data to optimize against. + +--- + +## v2.0.0 — 3-4 weeks, the daemon redesign + +The single largest architectural shift on the roadmap. Background and rationale captured at length elsewhere this session; summary here. + +### Single load-bearing principle + +> **The user is the unit of mesh participation, not the Claude session.** + +Every weird edge case from this session — the launch tax, the orphan owner, the per-session keypair churn, the MCP install/uninstall ritual, multi-Claude config corruption — comes from getting this one thing wrong today. Fix it once, structurally, and 70% of accumulated complexity vanishes. + +### Architecture + +``` +claudemesh.com (web identity + workspace admin) + │ + ▼ JWT +broker (unchanged) — wss://ic.claudemesh.com/ws + │ + ▼ ws per workspace +claudemesh-daemon (per user, launchd/systemd, persistent) + │ + ▼ unix socket + ┌────┴────┐ + ▼ ▼ +CLI verbs MCP push-pipe (~50 LoC) + │ + ▼ + claude (any number of sessions) +``` + +### What v2.0.0 ships + +- **`claudemesh-daemon`** — long-lived per-user process. One WS per workspace, kept alive across Claude session lifetimes. Listens on `~/.claudemesh/sockets/.sock`. Started by `claudemesh login`, persists across reboots. +- **HKDF-derived peer keypairs from JWT** — same identity across machines, no key copy ritual. Web sign-up = CLI sign-up = same row in `mesh_member`. +- **Stateless CLI verbs** — each existing command (`send`, `peers`, `topic`, `apikey`, `bridge`, `state`, `remember`, etc.) retargeted to dial the daemon socket. ~3000 LoC of plumbing deleted, ~500 LoC of glue added. +- **50-line MCP server** — dial daemon, forward inbound peer messages as `experimental.claude/channel` notifications. The push-pipe shrinks from ~150 LoC to ~50. +- **`claudemesh launch` deprecated** — replaced by ambient mode: `claude` with no flags. Launch becomes a one-line alias that prints "ambient mode now, just run `claude`" and exits. +- **"Mesh" → "workspace"** in the public surface. DB tables keep `mesh_*` names for migration sanity. + +### What v2.0.0 kills + +- `claudemesh launch` command — the 8-thing bootstrap was paying for state the daemon now owns persistently. +- `--dangerously-skip-permissions` — set once at install in `settings.json` allowedTools, never seen by the user again. +- `--dangerously-load-development-channels` — written into `~/.claude.json` once at install, never seen again. +- Per-session `CLAUDEMESH_CONFIG_DIR` tmpdir — daemon owns config. +- Per-session `CLAUDEMESH_DISPLAY_NAME` env var — daemon stores it. +- MCP install/uninstall ritual on every launch — MCP entry is permanent. +- Multi-Claude config corruption — only the daemon writes config. +- Orphan-owner bug (just fixed via backfill) — structurally impossible because web sign-up creates the member row. + +### What v2.0.0 keeps + +- Wire protocol, crypto primitives, broker schema — 100% unchanged. +- All CLI verb names — 100% unchanged (just retargeted). +- REST `/api/v1/*` surface — 100% unchanged. +- Web chat UI — 100% unchanged. +- Bridge peer feature — 100% unchanged. +- Topic semantics, ciphertext field, ephemeral DMs — 100% unchanged. + +### Cost + +- ~3 weeks focused engineering +- ~30% LoC reduction in the CLI package +- ~80% reduction in support load for "launch flags," "config corruption," "peer keypair lost," "owner has no member row" +- ~0 cost to broker, web app, schema, protocol — none of the deep parts change + +### Migration path (backwards-compatible at every step) + +1. **Week 1** — daemon binary + unix socket protocol + retarget two CLI verbs (`send`, `peers`) as the smoke test. Ship to alpha testers. +2. **Week 2** — retarget remaining verbs. HKDF-keypair migration with a one-shot `claudemesh migrate-identity` command for existing users. +3. **Week 3** — `claudemesh launch` becomes a deprecated alias. MCP server retargeted to daemon socket. Backfill: every existing user's daemon spins up on first `claudemesh` invocation. +4. **Cut v2.0.0**: remove deprecated launch alias one minor release later (v2.1.0) once metrics show no one's hitting it. + +--- + +## v0.3.0 — 4-6 weeks, the operator chapter + +For teams that want to run their own broker, encrypt at the topic level, or wire claudemesh to messaging surfaces beyond Claude Code. + +- **Per-topic HKDF encryption** — kills the "broker can read your messages" wart. Symmetric key derived from `mesh.root_key + topic.id`. Web client gets the topic key from the sealed root_key it already holds. +- **Self-hosted broker packaging** — single `docker-compose.yml`, postgres included. CLI accepts `--broker wss://...` to point anywhere. Federation primer. +- **WhatsApp gateway** — peer bot that forwards a topic to a WhatsApp group. +- **Telegram gateway** — same pattern. +- **Tag routing** — `claudemesh send tag:repo:billing "deployed"` lands at every peer working on that repo. Already protocol-supported, needs CLI ergonomics + dashboard surface. + +v0.3.0 is when teams that want to run their own broker can do so without paying us. Counterintuitively important: it's also when we can charge for hosted with a clean conscience. + +--- + +## v3.0.0 — Anthropic-blessed cut (conditional) + +Conditional on Anthropic shipping first-class agent-to-agent channels in Claude Code. We don't control the timing. + +When that lands: +- The 50-line MCP wrapper from v2.0.0 disappears. +- The daemon plugs directly into the native channel primitive. +- `--dangerously-load-development-channels` flag in `~/.claude.json` goes away. +- claudemesh becomes a "hosted backend for Claude's native multi-agent feature," not a "Claude Code extension." Marketing simplifies. + +Until then, v2.x ships with the MCP bridge. v3.0.0 is the migration target, not a planned feature. + +--- + +## Cross-cutting tracks (always-on, not version-gated) + +| Track | What it covers | Target version | +|---|---|---| +| Mobile | iOS peer app (thin: push + reply, same JWT identity) | v2.x | +| Browser peer (proper) | IndexedDB ed25519 + WebCrypto crypto_box for the dashboard. Today's web is REST-only; this makes it a true peer. | v2.x | +| Peer transcript queries | "Hey Claude2, what have you touched in the last hour?" cross-session memory primitive | v0.3.0+ | +| Mesh analytics | Volume, presence, handoff latency dashboards | v0.3.0 | +| Slack peer (first-party) | Today: build-your-own. Shipped natively. | v0.3.0 | + +--- + +## Deliberate exclusions + +| Idea | Why deferred | +|---|---| +| Custom bot framework / plugin marketplace | Premature — claudemesh barely has organic users. Build the user base first, then platform. | +| Voice channels | Out of scope. Different product. | +| Video chat | Same. | +| Email-as-peer (incoming SMTP → mesh) | Has demand from one user; ship if 3+ ask. | +| AI summarization of channels | LLM cost + scope creep. Users can wire their own with the existing message API. | +| Mobile push notifications via APNs/FCM | Wait for the iOS peer app, then revisit. | +| Reactions / threading | Not yet — would muddle the protocol surface for marginal value. Reconsider after v0.3.0 user feedback. | + +--- + +## Single-sentence summary + +**Polish v1.6.x → ship v1.7.0 demo → commit v2.0.0 daemon → open the operator chapter at v0.3.0 → plug into native channels at v3.0.0 when Anthropic ships them.** Each release stands on its own. The protocol, the schema, the broker, and the topics are all already correct — what changes is the lifecycle owner around them. diff --git a/docs/roadmap.md b/docs/roadmap.md index 9a17b67..7445b52 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -109,44 +109,118 @@ Spec: `.artifacts/specs/2026-05-02-v0.2.0-scope.md`. --- -## v0.2.0 — *next* +## v1.6.x — *patch line, polish what shipped* -The surface layer. The protocol is ready; these are gateways + routing -primitives. +Closes loose ends from the v1.6.0 cut so the v0.2.0 backend feels +production-grade before any new architectural work. - **Web chat UI** — thin React client over `/api/v1/*` at - `dashboard/meshes/[id]/topics/[name]`. Auto-issues an apikey for the - signed-in dashboard user. Compose, message stream, members sidebar. -- **Tag routing** — send to *any peer working on `repo:billing`*, - rather than by name -- **WhatsApp gateway** — a peer bot that forwards messages to/from - WhatsApp, so your mesh follows you off the laptop -- **Telegram gateway** — same pattern, different surface -- **Peer transcript queries** — let your Claude ask another Claude - *what have you touched in the last hour?* without a human in between -- **iOS peer app (thin)** — push + reply, same keypair, same identity -- **Per-topic encryption** — HKDF-derived symmetric keys from - `mesh_root_key + topic_id`. The current implementation base64-encodes - plaintext into the `ciphertext` field for forward-compat. -- **Custom migration runner** — replace drizzle's `_journal.json` - tracking with filename + sha256 in `mesh.__cmh_migrations`. Unblocks - every future schema change. + `dashboard/meshes/[id]/topics/[name]`. Auto-issues an apikey for + the signed-in dashboard user. Every mesh ships with a default + `#general` topic auto-created on creation. *Shipped 2026-05-02.* +- **Custom migration runner** — drizzle's `_journal.json` replaced + with filename + sha256 in `mesh.__cmh_migrations`. Unblocks every + future schema change. *Shipped 2026-05-02.* +- **Owner peer-identity at mesh creation** — web-first owners get a + `mesh.member` row at sign-up time. *Shipped 2026-05-02.* +- **Real-time push (SSE)** — replaces 5s polling on + `/api/v1/topics/:name/stream`. Sub-500ms message delivery. +- **Unread counts via `last_read_at`** — schema column already + exists; PATCH on scroll-to-bottom + chip on topic list. +- **Bridge end-to-end smoke test** — two-mesh forwarding validated + before any external demo. +- **`/v1/peers` includes humans** — synthetic presence rows for + active apikey sessions; the dashboard chat user becomes visible + to other peers. --- -## v0.3.0 — *later* +## v1.7.0 — *the demo cut* -The operator layer. Built for teams that want to run their own. +The release that turns claudemesh into a thing you can record and +show to non-technical audiences. +- **Member sidebar in the chat panel** — names, online dots, + presence summaries (free with SSE) +- **Topic search + member-mention autocomplete** — `@Mou` hot-keys + to `claudemesh send Mou ...` +- **Notification feed at `/dashboard`** — "you have N unread in + #deploys, 2 mentions in #incident" +- **First public blog post + recorded demo** — "claudemesh in 90 + seconds" video +- **Marketing site refresh** — screenshots from the real-time UI, + remove v0.2.0 stamps + +--- + +## v2.0.0 — *the daemon redesign* + +The single largest architectural shift. Promotes the persistent +thing (the user's account + identity) to a persistent process (the +daemon), demotes the ephemeral thing (the Claude session) to a thin +client. + +- **`claudemesh-daemon`** — long-lived per-user launchd / systemd + unit. One WebSocket per workspace, persistent across reboots and + Claude restarts. Listens on `~/.claudemesh/sockets/.sock`. +- **HKDF-derived peer keypairs** — same identity across machines, + no key copy ritual. Web sign-up = CLI sign-up = same crypto identity. +- **Stateless CLI verbs** — every existing command becomes a thin + socket client of the daemon. ~3000 LoC removed. +- **MCP server shrinks to ~50 LoC** — just a daemon-socket → + `experimental.claude/channel` adapter. +- **`claudemesh launch` deprecated** — ambient mode means `claude` + works with no flags. Launch becomes a one-line alias that prints + "ambient mode now, just run `claude`." +- **"Mesh" → "workspace" public surface** — DB tables keep + `mesh_*` names for migration sanity. + +Spec: `.artifacts/specs/2026-05-02-roadmap.md`. + +--- + +## v0.3.0 — *the operator layer* + +For teams that want to run their own broker, encrypt at the topic +level, or wire claudemesh to messaging surfaces beyond Claude Code. + +- **Per-topic HKDF encryption** — symmetric keys derived from + `mesh.root_key + topic.id`. Kills the "broker can read your + messages" wart. Today's `ciphertext` field is base64 plaintext. - **Self-hosted broker packaging** — one-command Docker compose, - Postgres included + Postgres included. The new migration runner (v1.6.x) makes this + practical. - **Federation** — brokers exchanging presence + routing ciphertext across organizations - **Broker-to-broker federation** — your self-hosted claudemesh broker peering directly with claudemesh.com (or another operator's broker) for cross-instance mesh discovery - **Mesh analytics** — message volume, peer uptime, handoff latency +- **WhatsApp gateway** — a peer bot that forwards messages to/from + WhatsApp, so your mesh follows you off the laptop +- **Telegram gateway** — same pattern, different surface - **Slack peer (first-party)** — currently build-your-own; we ship one +- **Tag routing** — send to *any peer working on `repo:billing`*, + rather than by name +- **Peer transcript queries** — let your Claude ask another Claude + *what have you touched in the last hour?* without a human in between +- **iOS peer app (thin)** — push + reply, same JWT identity + +--- + +## v3.0.0 — *Anthropic-native channels (conditional)* + +Migration target, not a planned feature — depends on Anthropic +shipping first-class agent-to-agent channels in Claude Code. When +that lands: + +- The MCP wrapper from v2.0.0 disappears entirely +- The daemon plugs directly into the native channel primitive +- `--dangerously-load-development-channels` flag goes away +- claudemesh becomes a "hosted backend for Claude's native + multi-agent feature" — marketing simplifies + +Until then, v2.x ships with the MCP bridge. ---