Skip to content

docs: reframe README around programmable/headless control (less Claude-specific) #36

Description

@gitcoder89431

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:

  1. 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
  2. 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"
  3. 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
  4. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions