Summary
The README currently leads with "MCP (Claude integration)" and explicitly mentions Claude and ~/.claude.json, which makes the project feel tightly coupled to one AI product.
However, the actual design of the CLI + MCP server is more generally useful:
- A programmable, scriptable, headless control surface over a single Syncthing folder
- Tools that a human dev (or any automation/agent) can use via stdio, not just Claude
Proposal
Rework the README to emphasize:
-
Primary positioning
- meshd as a programmable, scriptable, headless control surface for a self-hosted "Dropbox" folder (
~/meshd)
- TUI + CLI + stdio API for automation
- Syncthing as the underlying transport, but meshd as the opinionated UX
-
Use-case driven sections
- "For developers":
- Shared
~/meshd scratchpad across machines
- CLI flows:
meshd status, meshd devices, meshd errors, meshd ignore add
- Headless usage via
meshd status --json for bar widgets / scripts
- "For automation":
- Document
meshd mcp as a generic stdio API, not Claude-specific
- Show high-level examples: wait for sync, add ignores, check activity
- Frame it as "agents/automation" instead of "Claude"
-
MCP / agent section
- Rename section from "MCP (Claude integration)" to something like "Programmable API / MCP" or "Headless control and agents"
- Keep the Claude example, but:
- Move it after the generic explanation
- Phrase it as "Example: wiring into Claude via MCP" rather than the only path
-
Tone / phrasing
- Make the README feel public-facing and dev-oriented:
- Focus on problems solved (single-folder sync, cross-machine workflow, scriptable status)
- Explicitly call out that tools are designed for real developers and automation, not just one AI assistant
Acceptance Criteria
- README has a "Why this exists" or "Use cases" section describing:
- Terminal-first dev workflows with
~/meshd
- Headless / scriptable scenarios (status, errors, ignores)
- Agent / automation use without naming Claude as the primary target
- MCP section title and content use generic language ("agents", "automation", "MCP") and only mention Claude as an example
- No behavior changes; this is documentation-only
Summary
The README currently leads with "MCP (Claude integration)" and explicitly mentions Claude and
~/.claude.json, which makes the project feel tightly coupled to one AI product.However, the actual design of the CLI + MCP server is more generally useful:
Proposal
Rework the README to emphasize:
Primary positioning
~/meshd)Use-case driven sections
~/meshdscratchpad across machinesmeshd status,meshd devices,meshd errors,meshd ignore addmeshd status --jsonfor bar widgets / scriptsmeshd mcpas a generic stdio API, not Claude-specificMCP / agent section
Tone / phrasing
Acceptance Criteria
~/meshd