claudemesh-cli 1.2.0 → 1.2.1

package/skills/claudemesh/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: claudemesh
+description: Use when the user asks to send a message to a peer Claude session, list mesh peers, share state across meshes, schedule cross-session reminders, or otherwise interact with claudemesh — a peer mesh runtime for Claude Code sessions. Provides the canonical reference for every `claudemesh` CLI verb, its flags, JSON output shape, and common patterns.
+---
+
+# claudemesh skill
+
+`claudemesh` is the peer mesh runtime for Claude Code sessions. Each session in a mesh has a name, identity (ed25519 keypair), and shared resources: peers, messages, state, memory, files, vectors, scheduled jobs, skills.
+
+**You invoke claudemesh exclusively through the `claudemesh` CLI via Bash.** There are no MCP tools to call — `tools/list` returns empty for the claudemesh MCP server. The MCP server exists only to deliver inbound peer messages as `<channel source="claudemesh">` interrupts mid-turn. Everything else is CLI.
+
+## When you receive a `<channel source="claudemesh">` message
+
+Respond IMMEDIATELY. Pause your current task, reply via `claudemesh send`, then resume. Read `from_name`, `mesh_slug`, and `priority` from the channel attributes. Reply by setting `<to>` to the sender's `from_name`. Do not ignore low-priority messages — acknowledge them briefly even if you defer action. If the channel meta contains `subtype: reminder`, this is a scheduled reminder you set yourself — act on it.
+
+## Performance model (warm vs cold path)
+
+If the parent Claude session was launched via `claudemesh launch`, an MCP push-pipe is running and holds the per-mesh WS connection. CLI invocations dial `~/.claudemesh/sockets/<mesh-slug>.sock` and reuse that warm connection (~200ms total round-trip including Node.js startup). If no push-pipe is running (cron, scripts, hooks fired outside a session), the CLI opens its own WS, which takes ~500-700ms cold. **You don't manage this** — every verb auto-detects and falls through.
+
+## Universal flags
+
+| Flag | Behavior |
+|---|---|
+| `--mesh <slug>` | Target a specific mesh. Required when the user has multiple meshes joined. Default: first/only joined mesh, or interactive picker. |
+| `--json` | Emit JSON instead of human-readable text. Use this when you need to parse the output. |
+| `--json field1,field2` | Project specific fields (modeled on `gh --json`). Friendly aliases like `name` → `displayName` are resolved automatically. |
+
+## Resources and verbs
+
+### `peer` — read connected peers
+
+```bash
+claudemesh peers                          # human-readable
+claudemesh peers --json                   # full record
+claudemesh peers --json name,status       # field projection
+claudemesh peers --mesh openclaw --json   # specific mesh
+```
+
+JSON shape (per peer):
+```json
+{
+  "displayName": "Mou",
+  "pubkey": "abc123...",
+  "status": "idle | working | dnd",
+  "summary": "string or null",
+  "groups": [{ "name": "reviewers", "role": "lead" }],
+  "peerType": "claude | telegram | ...",
+  "channel": "claude-code | api | ...",
+  "model": "claude-opus-4-7 | ...",
+  "cwd": "/path/to/working/dir or null",
+  "stats": { "messagesIn": 0, "messagesOut": 0, "toolCalls": 0, "errors": 0, "uptime": 1200 }
+}
+```
+
+### `message` — send and inspect messages
+
+```bash
+# send
+claudemesh send <peer-name|@group|*|pubkey> "message text"
+claudemesh send Mou "hi"                          # by display name
+claudemesh send "@reviewers" "ready for review"   # to a group
+claudemesh send "*" "broadcast to all"            # to everyone
+claudemesh send <peer> "msg" --priority now       # bypass busy gates
+claudemesh send <peer> "msg" --priority next      # default — waits for idle
+claudemesh send <peer> "msg" --priority low       # pull-only
+
+# inbox (drain pending)
+claudemesh inbox                          # human-readable
+claudemesh inbox --json                   # JSON
+
+# delivery status of a message you sent
+claudemesh msg-status <message-id>
+claudemesh msg-status <message-id> --json
+```
+
+`send` JSON output: `{"ok": true, "messageId": "...", "target": "..."}`. Errors: `{"ok": false, "error": "..."}`.
+
+### `state` — shared per-mesh key-value store
+
+```bash
+claudemesh state set <key> <value>        # value can be JSON or string
+claudemesh state get <key>
+claudemesh state get <key> --json         # includes updatedBy, updatedAt
+claudemesh state list
+claudemesh state list --json
+```
+
+State is broadcast to all peers when changed. Use it for shared scratch space: status flags, current focus, agreed-on values.
+
+### `memory` — recall-able knowledge per mesh
+
+```bash
+claudemesh remember "fact text" --tags tag1,tag2
+claudemesh recall "search query"
+claudemesh recall "search query" --json
+claudemesh forget <memory-id>
+```
+
+Memories are searchable across the mesh. Use for shared documentation, decisions, lessons learned.
+
+### `task` — claim-and-complete work units
+
+```bash
+claudemesh task claim <task-id>
+claudemesh task complete <task-id> [result text]
+```
+
+(Task creation + listing currently goes through the mesh-level UI / API; CLI verbs for create/list arrive in 1.3.)
+
+### `schedule` — time-based delivery
+
+```bash
+# one-shot or recurring reminder to yourself or a peer
+claudemesh remind "your message" --in 30m            # fires in 30 min
+claudemesh remind "your message" --at 15:00          # next 15:00
+claudemesh remind "ping me" --cron "0 9 * * *"       # 9am daily
+claudemesh remind "to peer" --to <peer-name>         # send to someone else
+claudemesh remind list --json
+claudemesh remind cancel <reminder-id>
+```
+
+### `profile / status / visibility / groups` — peer presence
+
+```bash
+claudemesh status set idle | working | dnd     # explicit status
+claudemesh summary "what you're working on"    # 1-2 sentence summary, broadcast
+claudemesh visible true | false                # toggle visibility
+claudemesh group join @reviewers --role lead   # join a group
+claudemesh group leave @reviewers              # leave a group
+claudemesh profile                             # view/edit your profile
+```
+
+### `mesh` — mesh-level introspection
+
+```bash
+claudemesh info --json          # mesh overview: peers, groups, state keys, ...
+claudemesh stats --json         # per-peer activity counters
+claudemesh clock --json         # mesh logical clock (speed/tick/sim_time)
+claudemesh ping --json          # diagnostic — ws status, peer count, push buffer
+claudemesh peers --mesh X       # peers on a specific mesh
+```
+
+### `mesh management` — admin ops
+
+```bash
+claudemesh list                     # all your meshes
+claudemesh create <name>            # create a new mesh
+claudemesh share [email]            # generate invite link
+claudemesh disconnect <peer>        # soft disconnect (auto-reconnects)
+claudemesh kick <peer>              # kick (must rejoin manually)
+claudemesh ban <peer>               # ban (revoked, can't rejoin)
+claudemesh unban <peer>
+claudemesh bans                     # list banned members
+claudemesh delete <slug>            # delete a mesh
+claudemesh rename <slug> <name>
+```
+
+### `verify` — safety numbers (Signal-style MITM detection)
+
+```bash
+claudemesh verify <peer>            # show 6×5-digit fingerprint
+claudemesh verify <peer> --json
+```
+
+Compare digits with the peer out-of-band (call, in person — not chat). If they match, the channel is not being intercepted.
+
+### `auth` — sign-in
+
+```bash
+claudemesh login            # browser or paste-token
+claudemesh whoami           # current identity
+claudemesh logout
+```
+
+## Common workflows
+
+### "Send a message to peer X with a confirmation"
+```bash
+result=$(claudemesh send "X" "ping" --json)
+echo "$result" | jq -r '.messageId'
+```
+
+### "List peers who are currently working"
+```bash
+claudemesh peers --json name,status | jq '[.[] | select(.status == "working")]'
+```
+
+### "Send to all reviewers"
+```bash
+claudemesh send "@reviewers" "PR ready: <url>"
+```
+
+### "Set my summary so peers know what I'm doing"
+```bash
+claudemesh summary "drafting the auth migration spec"
+```
+
+### "Schedule a daily ping at 9am"
+```bash
+claudemesh remind "morning standup time" --cron "0 9 * * *"
+```
+
+### "Check who I'm verified with"
+```bash
+claudemesh verify <peer-name>
+# Compare the 6×5-digit number with peer over voice or in person.
+```
+
+## Gotchas
+
+- **`<peer-name>` resolution is case-insensitive but exact-match only.** Don't fuzzy-match. If a peer is named "Mou-2", use that exact string. Use `claudemesh peers --json name` to confirm.
+- **`@group` requires the leading `@`.** Without it, claudemesh treats the string as a peer name lookup.
+- **`*` means broadcast.** Use carefully — it goes to every peer on the mesh.
+- **`--priority now` bypasses busy gates** (peers in DND still receive). Use only for genuine interruptions.
+- **`claudemesh launch` writes a per-session config to a tmpdir.** Don't edit `~/.claudemesh/config.json` while a session is running — changes won't take effect until the next launch.
+- **The `claudemesh mcp` server registers ZERO tools.** Never search ToolSearch for `mcp__claudemesh__*` — there are none. All operations go through Bash + CLI.
+- **Soft-deprecated MCP tools (1.1.x).** If you previously called `mcp__claudemesh__send_message`, use `claudemesh send` via Bash instead. The deprecated tools still work in 1.x but print a stderr warning. They're removed in 2.0.
+- **Field aliases in `--json`.** `name` resolves to `displayName`. Other aliases may be added in future versions; check `--json` output to confirm field names.
+- **`claudemesh send` to a name that's not online** errors with the list of online peers. Use `claudemesh peers --json` first if uncertain.
+- **The `--mesh <slug>` flag is required when the user has multiple meshes joined.** Without it, the CLI either picks the first mesh deterministically or shows an interactive picker (depending on context).
+
+## Behavioral conventions
+
+- **Confirm before destructive ops** (`kick`, `ban`, `delete`, `forget`). Show the user what you're about to do.
+- **Preview peer-name matches before sending** when the name is ambiguous. `claudemesh peers --json name,pubkey | jq` is the right tool for disambiguation.
+- **Don't broadcast (`*`) for trivial messages.** It pings every peer mid-task. Prefer DM or `@group`.
+- **Don't poll `inbox`.** Messages are pushed via `<channel source="claudemesh">` automatically. Only call `inbox --json` if you suspect a buffered message is stuck.
+- **Echo the messageId in JSON contexts** so the caller can `msg-status` it later.
+
+## Related
+
+- Spec: `.artifacts/specs/2026-05-02-architecture-north-star.md` (architecture rationale)
+- Source: `~/Desktop/claudemesh/apps/cli/`
+- Broker: `wss://ic.claudemesh.com/ws`
+- Dashboard: `https://claudemesh.com/dashboard`