Dear User

Dear User

Your AI agent works for you — but how well do you work together?

Dear User is an open-source tool that audits your Claude Code setup and tells you exactly what to fix. It scores your collaboration, finds leaked secrets and config conflicts, and checks system health — all locally, nothing uploaded unless you explicitly share your Wrapped card.

claude mcp add --scope user dearuser -- npx -y @poisedhq/dearuser-mcp@latest

Then ask Claude: *"Analyze my collaboration with Claude"*

Landing: dearuser.ai · Feedback: use the feedback tool in Claude, or open an issue

---

What it does

Dear User is an MCP server (Model Context Protocol — the plugin system Claude Code and Claude Desktop use). Once installed, it shows up as a set of tools your agent can call. No GUI, no sign-up, no cloud account.

Three local reports, one shareable Wrapped card, one feedback channel:

Plus helpers: onboard (7-step guided setup), history (trend without re-scanning), help (menu), implement_recommendation, dismiss_recommendation, share_report (Wrapped-only upload).

Launch highlights

• Shareable Wrapped — run wrapped, then share_report to get a dearuser.ai/r/ URL for your stats card. Anonymized before upload (paths collapsed to basenames, emails stripped, secrets redacted). Collab/security/health reports stay local — findings can carry business context that isn't safe to auto-share.
• 12-category secret scanner — OpenAI, Anthropic, GitHub, AWS, Stripe, Slack, Google, Supabase, Vercel, private keys, generic env secrets, bearer tokens. Scans CLAUDE.md / AGENTS.md, memory files, skills, hooks.
• AGENTS.md native support — first-class input alongside CLAUDE.md. Works out of the box for Cursor, Codex, Aider, Cline, Zed and anyone following the Linux Foundation cross-tool standard. Both files in the same directory? We merge them.
• Semantic conflict detection (new) — finds rules that contradict each other even when they don't share keywords. "Commit often" vs. "ask before commit" gets flagged.
• Score calibrated against reality — two studies: 988 public Claude Code setups with substrate committed (median 32/100, max 63) and 2,895 standalone CLAUDE.md files (median 18, max 60). The substrate corpus is the apples-to-apples benchmark for live scores. See research/calibration/ for both studies.

Install

One command per client. Full guide: docs/install.md.

Claude Code (CLI)

claude mcp add --scope user dearuser -- npx -y @poisedhq/dearuser-mcp@latest

Restart Claude Code afterwards so the tools appear.

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{

"mcpServers": { "dearuser": { "command": "npx", "args": ["@poisedhq/dearuser-mcp"] } } }

Cursor, Windsurf, Cline, Zed — see docs/install.md.

Optional: install the slash commands (see Commands for the full list) so you can type /dearuser-collab instead of asking in prose:

npx -p @poisedhq/dearuser-mcp dearuser-install-skills

Your first 5 minutes

After installing, restart your client and try these in order:

1. Baseline scan:

   Run Dear User collab on this project

You'll get a persona (Vibe Coder / Senior Developer / Indie Hacker / Venture Studio / Team Lead), a 0-100 score across 7 categories, and 3-10 concrete recommendations.

1. Security sweep:

   Run Dear User security

Checks your agent contract (CLAUDE.md or AGENTS.md), memory, skills and hooks for leaked tokens, injection surfaces and rule conflicts.

1. Share the result (optional):

   Share my collab report

Returns a dearuser.ai/r/ link. Anonymized before upload. You choose whether to paste it anywhere.

Example output from collab:

Persona: Indie Hacker (87% confidence)

Score: 73 / 100

Top friction: • Quality Standards — no test-before-commit rule in CLAUDE.md • Memory Health — 2 memory files haven't been touched in 90+ days • Communication — no language preference stated (English vs Danish mixing)

Recommendations (3 shown, 5 total):

1. Add a "Session start protocol" block to CLAUDE.md (apply with: implement_recommendation)
2. Rotate the OpenAI key leaked in ~/.claude/memory/api-notes.md
3. Merge overlapping skills: deploy-check and ship-check share 80% of their rules

Commands

Eight slash commands ship with Dear User. Ask your agent by name, or type the slash command if you installed them with dearuser-install-skills.

Three in-chat actions the agent can call for you: share_report (upload a Wrapped card to dearuser.ai/r/ ), implement_recommendation (apply a pending recommendation), dismiss_recommendation (mark one irrelevant).

Privacy

Dear User is local-first. Your scans stay on your machine:

• Your agent contract (CLAUDE.md or AGENTS.md), memory, skills, hooks and session metadata are read but never uploaded
• Results are stored in ~/.dearuser/dearuser.db (SQLite, WAL mode)
• The optional localhost dashboard reads from that DB — nothing is transmitted
• Dear User reads session metadata only (counts, lengths) — never your actual conversation content
• No API keys required, no sign-up, no telemetry

The only exceptions are things you explicitly trigger:

• `share_report` (Wrapped only) — your Wrapped card is anonymized (paths collapsed, emails stripped, anything matching our secret patterns redacted) and uploaded to dearuser.ai so you can share a URL. Your local DB is not modified. You can set an expires_at to auto-expire the link. Collab/security/health reports are NOT shareable — findings can carry business context (project names, client names, architecture notes) we don't think should live on a public URL.
• `feedback` — when you call the feedback tool, your message goes to our Supabase inbox. That's the whole point of the tool. We don't attach your scans or files — only the text you write.

No other tool transmits anything. If share_report isn't configured with DEARUSER_SUPABASE_URL + DEARUSER_SUPABASE_SERVICE_KEY, it errors out cleanly and the rest of Dear User keeps working.

Full privacy details: docs/privacy.md.

How it works

Your files (CLAUDE.md or AGENTS.md, memory, hooks, skills, sessions)

│ Scanner ──► Parser ──► Engines (scoring, secrets, conflicts, health) │ Persona detection → Scoring → Gap analysis → Recommendations │ Feedback loop (tracks which recommendations you implemented) │ ~/.dearuser/dearuser.db ← dashboard reads from here

• 5 personas detected from your setup — each gets tailored recommendations
• 7 scoring categories: Role Clarity, Communication, Autonomy Balance, Quality Standards, Memory Health, System Maturity, Coverage
• Feedback loop: Dear User remembers what it recommended. Next run, it checks which ones you implemented and shows the score delta.

Who it's for

• "Vibe coders" — you prompt Claude and ship product, but you're never quite sure if your setup is actually working. Dear User tells you.
• Senior developers — you want a fast audit for leaked secrets, config drift and rule conflicts without wiring up a custom lint pipeline.
• Indie hackers / solo founders — you've accumulated hooks, skills and memory across projects. Dear User surfaces what's orphaned or contradicting itself.
• Team leads — you want a local audit of your team's shared agent setup. Collab, security and health reports stay on your machine; only your personal Wrapped card can be shared publicly.

Repository layout

• mcp/ — @poisedhq/dearuser-mcp npm package (the MCP server). See mcp/README.md for development notes.
• web/ — dearuser.ai landing + share-report pages (Astro).
• docs/ — install guide, privacy doc, per-platform setup (Supabase/GitHub/Vercel for the optional security platform advisors).
• research/ — calibration data + architecture notes we're willing to share.

Contributing

See CONTRIBUTING.md. Bug reports and small fixes welcome via GitHub issues and PRs.

Community & support

• GitHub Discussions — questions, ideas, "how do I…", show-and-tell
• GitHub Issues — reproducible bugs and feature requests
• Feedback inbox — private notes; or use the feedback MCP tool from inside Claude

Links

• dearuser.ai — landing page
• Install guide · Privacy · Setup for platform advisors

License

Dear User is MIT-licensed. See LICENSE.

Open-core commitment: everything in this repo is MIT and stays MIT. If we ever build team or hosted features (agency dashboards, cross-project trend lines, vertical-specific benchmarks), they'll live in separate repos with their own license — never by pulling pieces out of this one.