Skip to content

Install UX epic: daemon supervision + cloud bootstrap + MCP registration + update checks #190

@Gradata

Description

@Gradata

Problem

gradata install does too little. Four self-install gaps surfaced in a single diagnostic session on a fresh WSL host:

# Gap Symptom
1 No daemon supervision After install, :8765 is not listening. Dashboard shows "Local Gradata daemon not running. Run gradata sync locally, then refresh." User must manually python -m gradata.daemon every boot.
2 No cloud credential bootstrap gradata sync fails with no cloud credential found. Run gradata cloud enable --key ... first. ~/.gradata/config.toml is never created by the installer.
3 MCP registration is per-client and incomplete gradata install configures hooks only. Cursor users get an MCP entry via separate setup; Claude Code / Hermes / Codex users get nothing. The server itself works — wiring is the gap.
4 No update check CLI has zero self-update awareness. No pip index versions check, no update available flag in gradata doctor. Users silently run stale versions for weeks.

Proposed fix — gradata install should:

  • Write ~/.config/systemd/user/gradata-daemon.service on Linux/WSL (with systemd=true check); equivalent launchd plist on macOS; Windows service on native Windows. Run systemctl --user enable --now gradata-daemon (or loginctl enable-linger for headless WSL).
  • Prompt for cloud key during gradata install (skippable with --no-cloud). Write ~/.gradata/config.toml with the key. Verify with one round-trip to api.gradata.ai.
  • Detect installed agent clients (Cursor, Claude Code, Hermes, Codex, Gemini) and register the gradata MCP server in each. Idempotent — skip if already present. Currently we only handle Cursor implicitly.
  • Add gradata doctor update check: query PyPI once per day, cache result, emit update available: 0.7.5 -> X.Y.Z line. Bonus: gradata self-update subcommand that runs pip install --upgrade gradata.

Acceptance criteria

  • Fresh pip install gradata && gradata install --agent claude-code on a clean WSL host results in:
    1. :8765 listening within 5 seconds of install completing
    2. gradata cloud status shows sync_enabled: True (if key provided) or a clear "run gradata cloud enable" hint (if --no-cloud)
    3. claude mcp list shows the gradata entry
    4. gradata doctor exits 0 with no [!] or [-] markers
  • Same on macOS via launchd
  • Re-running gradata install is idempotent (no duplicate service units, no duplicate MCP entries)

Evidence

Diagnostic session 2026-05-13 confirmed all four gaps on a working WSL install of gradata 0.7.5 (editable, from /home/olive/work/gradata-sdk/Gradata). The MCP server binary itself responds correctly to an initialize handshake — code is fine, wiring is the gap.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestinstall-uxInstall / onboarding UX gaps

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions