docs(roadmap): refresh after v1.6.0 ships + add daemon redesign target
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) <noreply@anthropic.com>
This commit is contained in:
Alejandro Gutiérrez
194
.artifacts/specs/2026-05-02-roadmap.md
Normal file
194
.artifacts/specs/2026-05-02-roadmap.md
Normal file
@@ -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/<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.
|
||||
|
||||
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.
|
||||
118
docs/roadmap.md
118
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/<workspace>.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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user