claudemesh/.artifacts/specs/2026-05-02-roadmap.md

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/<workspace>.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.

What's load-bearing about today's flag

--dangerously-load-development-channels server:claudemesh does two things:

1. Loads the claudemesh MCP server.
2. Tells Claude Code to treat its experimental.claude/channel notifications as runtime channel events.

The flag is named dangerously-load-development-channels specifically because the channel API is experimental and unstable. Some opt-in mechanism will always be required for Claude Code to receive external events from a third-party process — that's a security-model invariant, not a quirk of today's flag. What changes at v3.0.0 is the form of the opt-in, not its existence.

Two scenarios depending on Anthropic's choice

Scenario A — MCP-channel API graduates. The same MCP-based push primitive becomes stable.

• MCP wrapper stays (still translates ws://broker → MCP notification).
• The --dangerously-load-development-channels flag is replaced by a stable settings.json entry — e.g. mcpServers.claudemesh.acceptChannelNotifications = true.
• The experimental. prefix on the notification namespace goes away.
• Net user-visible change: nothing, because we already write the flag once at install and the user never sees it. The migration is internal: swap the install logic to write the new settings entry instead of the old flag.

Scenario B — non-MCP transport ships. Anthropic introduces a sidecar IPC, a native WebSocket subscription declared in settings, or some other primitive.

• The 50-line MCP wrapper from v2.0.0 disappears.
• The daemon plugs into the new transport directly.
• Some opt-in config is still required (settings.json entry, environment variable, etc.) — Claude Code must know to subscribe to the daemon's channel.
• Net user-visible change: still nothing if our claudemesh install adapts to write the new opt-in form.

What disappears regardless

• The experimental. prefix on the channel API (it stabilizes).
• The dangerously- framing of the flag (the API is no longer experimental).
• The "you have to pass a launch flag to load development channels" mental model.

What stays regardless

• An opt-in mechanism somewhere (security model invariant).
• The daemon as the lifecycle owner.
• The protocol, schema, broker, topics, web chat — all unchanged.

Marketing pivot

claudemesh becomes a "hosted backend for Claude's native multi-agent feature" rather than a "Claude Code extension." The product story simplifies regardless of which shape ships, because the user no longer has to think about MCP servers, dangerous flags, or experimental APIs — claudemesh is just there.

Until v3.0.0 lands, v2.x ships with the MCP bridge under the existing flag. 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.