clavitor/docs/RESEARCH.md

# Clavitor — Research Report

*Generated: 2026-02-28*

---

## Task 1: Chrome Extension Password Manager — Top User Complaints

### Research Sources
- r/1Password, r/Bitwarden, r/Lastpass, r/Dashlane (Reddit threads 2023–2026)
- 1Password Community forums (1password.community)
- Chrome Web Store reviews (via chrome-stats.com)
- Search: complaint patterns across all four major extensions

---

### Top 10 Universal Complaints (cross-PM)

---

#### 1. Extension slow/unresponsive — "Loading..." forever
**Severity:** 🔴 Very High

**What:** Extension popup opens to grey spinner or "Loading..." that never resolves. Clicking the icon does nothing, or crashes with "has crashed." On M1/M2 Macs with 1Password 8, users report waiting 5–15 seconds. 1Password community thread (July 2025): "1Password - Password Manager has crashed" — autofill stops working entirely.

**Frequency:** Extremely common for 1Password (multiple threads per month in 2025), intermittent for Bitwarden.

**Does Clavitor solve it?**
Yes. Clavitor is a local binary with no cloud sync delay, no Electron overhead. Extension calls localhost:8765 directly. Response time is bounded by local SQLite query, not external auth sessions. Eliminates the "cloud auth timeout" root cause.

---

#### 2. Autofill doesn't trigger / fills wrong field
**Severity:** 🔴 Very High

**What:** Extension fails to detect username/password fields, fills into wrong input (e.g., fills username into search bar), or injects credentials into OTP fields. Common on SPAs (React, Next.js), iframe-heavy sites, non-standard form structures.

**Frequency:** Nearly every subreddit has a "why doesn't it autofill on [site]?" thread weekly.

**Does Clavitor solve it?**
Partially. Clavitor has LLM-powered field mapping (/api/ext/map). Instead of CSS selector heuristics, the extension asks the LLM "which field on this page is the username field?" — fundamentally better than regex/attribute matching. Real competitive advantage.

---

#### 3. Extension breaks after browser update
**Severity:** 🔴 High

**What:** Chrome 127, 132, and others broke autofill for multiple PMs simultaneously. Users reinstall, clear session, re-authenticate. Recurring every few months.

**Frequency:** High — peaks after each Chrome major release.

**Does Clavitor solve it?**
Somewhat. Clavitor's extension is minimal — only fetch() calls to localhost, no native messaging host dependency like 1Password 8 requires. Fewer integration points = fewer Chrome API breakage surfaces.

---

#### 4. Requires desktop app to be running (1Password-specific)
**Severity:** 🔴 High for 1Password users

**What:** 1Password 8 requires the desktop app running AND connected. If the app is asleep, needs biometric, or updates itself — the extension fails. "Why does a browser extension need a desktop app?"

**Frequency:** Extremely common — structural issue with 1Password 8's architecture. #1 complaint in r/1Password 2024–2025.

**Does Clavitor solve it?**
Yes — completely. Clavitor runs as a standalone binary service. No desktop app, no IPC bridge, no native messaging.

---

#### 5. Popup/inline icon interferes with form input
**Severity:** 🟡 Medium-High

**What:** Autofill suggestion overlay covers UI elements, blocks "Forgot password" links, or triggers on unwanted fields (OTP, search bars, credit card fields mid-checkout). Bitwarden's inline menu cited as intrusive.

**Frequency:** Common, especially on mobile-optimized sites viewed on desktop.

**Does Clavitor solve it?**
Partially. LLM field mapping is invoked on-demand rather than injecting icons into every text field. Extension can activate on explicit keyboard shortcut or toolbar click only. Design choice, not a technical constraint.

---

#### 6. Master password / re-authentication nagging
**Severity:** 🟡 Medium-High

**What:** Extensions lock after short timeouts (especially LastPass, Dashlane) and demand re-entry of master password. Biometric unlock flaky or absent. Dashlane on Android 15 broke autofill entirely until May 2025.

**Frequency:** High for LastPass (aggressive timeout defaults), medium for others.

**Does Clavitor solve it?**
Yes. Clavitor uses WebAuthn for unlock (biometric first-class). Session management is local, no server-side token expiry.

---

#### 7. Doesn't detect/save new passwords correctly
**Severity:** 🟡 Medium

**What:** After creating an account or changing a password, extension either doesn't offer to save, shows prompt at wrong time, or saves wrong value. Broken "update password" detection is a top LastPass complaint.

**Frequency:** Common, especially after password change flows.

**Does Clavitor solve it?**
Partially. LLM field mapping can detect password confirmation fields more reliably. However, explicit "save new password" detection flow needs to be built into the extension (not in current SPEC).

---

#### 8. Focus stealing / typing hijacked (Windows 1Password)
**Severity:** 🟡 Medium (Windows-specific)

**What:** While typing master password in extension popup, 1Password on Windows opens the full desktop app, stealing keyboard focus mid-password. Users re-type. Windows IPC behavior issue.

**Frequency:** Frequently cited in r/1Password Windows threads 2024.

**Does Clavitor solve it?**
Yes — by design. No desktop app, no IPC, no focus stealing possible.

---

#### 9. Poor TOTP / 2FA integration
**Severity:** 🟡 Medium

**What:** Users want one-click TOTP autofill alongside username+password. 1Password does this but slowly. Bitwarden requires Premium. LastPass keeps breaking TOTP autofill after updates.

**Frequency:** Medium — requested frequently, implementation quality varies.

**Does Clavitor solve it?**
Yes. TOTP is first-class in Clavitor (L1 level, /api/ext/totp/:id). Extension fetches live TOTP code on demand. Autofill flow can include TOTP automatically.

---

#### 10. Privacy / trust concerns (cloud sync, data breaches)
**Severity:** 🟡 Medium-High (growing)

**What:** LastPass 2022 breach permanently damaged trust. Users migrating cite "I don't want my vault on their servers." 1Password's subscription SaaS model eroded trust with some power users. Bitwarden self-hosting is popular for this reason.

**Frequency:** Always-present background concern; growing with AI-powered cloud features.

**Does Clavitor solve it?**
Yes — completely. Local-only, no cloud, no subscription, no external service. SPEC: "No cloud, no subscriptions." Strongest selling point vs. established players.

---

### Summary Table

| # | Complaint | 1PW | BW | LP | DL | Clavitor Solves? |
|---|-----------|-----|----|----|-----|---------------|
| 1 | Slow/spinner/crash | XX | X | X | X | YES (local) |
| 2 | Autofill wrong/misses | X | X | X | X | YES (LLM mapping) |
| 3 | Breaks after browser update | X | X | X | X | Reduced risk |
| 4 | Requires desktop app | XX | OK | OK | OK | YES (none needed) |
| 5 | Icon intrudes on form | X | X | X | X | Design choice |
| 6 | Re-auth nagging | X | X | XX | X | YES (WebAuthn/local) |
| 7 | Save/update detection | X | X | XX | X | Needs work |
| 8 | Focus stealing (Win) | XX | OK | OK | OK | YES (N/A) |
| 9 | Poor TOTP integration | ~OK | ~OK$ | X | ~OK | YES (first-class) |
| 10 | Cloud trust/breach risk | X | OK(self) | XX | X | YES (local-only) |

---

## Task 2: Clavitor in Claude Code / Codex / Cursor (no OpenClaw)

### Overview
Developers using Claude Code, Codex CLI, or Cursor in a plain terminal don't have OpenClaw running. Clavitor's MCP endpoint and CLI make it useful in all three scenarios.

---

### Option 1: MCP Server — Claude Code

Claude Code stores MCP configs in multiple locations. For a user-global tool like a password vault:

**Config file locations (Claude Code):**
- `.mcp.json` — in project root (version-controlled, team-shared)
- `~/.claude.json` — user-global under project path entry
- `~/.claude/settings.json` — user-global
- `.claude/settings.local.json` — project-local, not committed

**Option A: Already-running clavitor server (HTTP transport)**
```bash
# Add via CLI
claude mcp add clavitor --transport http http://localhost:8765/mcp
```

This writes to `~/.claude.json`. Works immediately if clavitor is running.

**Option B: Stdio transport (clavitor as MCP subprocess)**

Add to `.mcp.json` in project root:
```json
{
  "mcpServers": {
    "clavitor": {
      "command": "clavitor",
      "args": ["--mcp"],
      "env": {
        "VAULT_KEY": "${VAULT_KEY}",
        "DB_PATH": "${HOME}/.clavitor/vault.db"
      }
    }
  }
}
```

Enable project MCP servers in `.claude/settings.json`:
```json
{
  "enableAllProjectMcpServers": true
}
```

Or whitelist specific servers:
```json
{
  "enabledMcpjsonServers": ["clavitor"]
}
```

**Option C: User-global via `~/.claude.json`**
```json
{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "clavitor": {
          "command": "clavitor",
          "args": ["--mcp"],
          "env": {
            "VAULT_KEY": "your-vault-key",
            "DB_PATH": "/Users/you/.clavitor/vault.db"
          }
        }
      }
    }
  }
}
```

**What this gives Claude Code:**
- `clavitor_get(title)` — fetch credential by name (L1 only)
- `clavitor_search(query)` — search entries
- `clavitor_totp(entry_id)` — get live TOTP code
- Claude can: "deploy to production using clavitor_get('AWS_PROD')" inline

---

### Option 2: CLI Usage — Direct Shell

Any AI coding tool that runs shell commands can use clavitor:

```bash
# Get a credential
clavitor get "GitHub PAT"

# Get specific field
clavitor get "GitHub PAT" --field password

# Search entries
clavitor search "AWS"

# Get TOTP code
clavitor totp "GitHub"
```

Claude Code's Bash tool and Codex CLI can shell out to these. Zero configuration needed.

---

### Option 3: Environment Variable Injection

```bash
# Inject all L1 credentials as env vars for subprocess
clavitor run -- npm run deploy

# Inject specific entries
clavitor run --entry "DATABASE_URL" --entry "REDIS_URL" -- python manage.py migrate

# Works with any tool
clavitor run -- docker-compose up
clavitor run -- terraform apply
```

Secrets never touch disk, never appear in `ps aux`, injected only for subprocess lifetime. Best pattern for CI/CD.

---

### Option 4: .env File Generation

```bash
# Generate .env from entries tagged "project:myapp"
clavitor export --tag "project:myapp" --format dotenv > .env

# Specific entries
clavitor export --entry "DATABASE_URL" --entry "API_KEY" --format dotenv > .env

# JSON for scripts
clavitor export --format json --entry "GitHub PAT" | jq '.password'
```

Familiar to every developer. Zero MCP knowledge required.

---

### Option 5: Cursor Integration

Cursor uses same MCP config format as Claude Desktop:

```json
// ~/.cursor/mcp.json  (or Cursor settings → MCP)
{
  "mcpServers": {
    "clavitor": {
      "command": "clavitor",
      "args": ["--mcp"],
      "env": {
        "VAULT_KEY": "your-key-here",
        "DB_PATH": "/Users/you/.clavitor/vault.db"
      }
    }
  }
}
```

Or with running server (HTTP):
```json
{
  "mcpServers": {
    "clavitor": {
      "url": "http://localhost:8765/mcp"
    }
  }
}
```

---

### Option 6: Codex CLI (OpenAI)

Codex CLI supports MCP via `~/.codex/config.toml`:

```toml
[mcp_servers.clavitor]
command = "clavitor"
args = ["--mcp"]

[mcp_servers.clavitor.env]
VAULT_KEY = "your-key"
DB_PATH = "/Users/you/.clavitor/vault.db"
```

---

### Key Insight: "No OpenClaw" Pitch

For developers not using OpenClaw, clavitor's value propositions:
1. **MCP** — AI assistant reads credentials directly, no copy-paste, no shell injection risk
2. **`clavitor run --`** — secrets injected as env vars for deploy scripts
3. **`.env` export** — familiar workflow, no new mental model
4. **TOTP in terminal** — no phone needed during deploy

---

## Task 3: Where/How to Announce Clavitor in the OpenClaw Community

### Channel 1: ClawHub — `github.com/openclaw/clawhub`

**What it is:** Official OpenClaw skills registry. 5,700+ skills. Primary discovery mechanism — users run `clawhub install <name>`.

**Submission process:** Fork repo → add `clavitor/` folder with `SKILL.md` + assets → open pull request. Contribution guidelines in `CONTRIBUTING.md`.

**After merge:** `clawhub install clavitor` works globally.

**What they care about:** Working SKILL.md, clear description, functional install.

**Ideal skill description:**
> Local password vault with MCP integration for AI agents. Provides credential access, TOTP generation, and secret management without cloud sync. Two-tier encryption: L1 (AI-readable) + L2 (device-only). Includes Chrome extension with LLM-powered autofill.

**Priority: HIGH — do this first. Everything else references the skill.**



---

### Channel 2: GitHub Discussions — `github.com/openclaw/openclaw/discussions`

**What it is:** Main technical discussion forum. Active with developers building on OpenClaw.

**What they care about:** New integrations, security tools, MCP servers. Posts with working code examples get traction.

**Format:** Detailed technical post. Show config, show what it enables. Link to ClawHub entry.

**Ideal announcement post:**
> **Clavitor — local password vault with MCP for OpenClaw**
>
> Single Go binary, SQLite, two-tier encryption (L1 AI-readable, L2 client-only). Your agent calls clavitor_get("GitHub PAT") directly via MCP. Chrome extension with LLM-powered autofill. No cloud, no subscription.
>
> clawhub install clavitor

---

### Channel 3: Discord — `discord.gg/clawd`

**What it is:** Primary community chat. "Community for Clawdbot builders — post your workflow, stack, config snippets, results."

**What they care about:** Practical demos. Copy-pasteable configs. "What does this let me do today?"

**Format:** Post in #skills or #showcase. Include: 2-sentence description + install command + example MCP config block + screenshot/GIF.

**Ideal announcement:**
> Just published clavitor to ClawHub — a local password vault with MCP integration. Your agent can fetch credentials and TOTP codes directly, zero cloud dependency. Two-tier encryption: L1 for AI reads, L2 stays on device.
>
> clawhub install clavitor

---

### Channel 4: X — @openclaw community

**What it is:** @openclaw has an X Community ("OpenClaw Community," 1.6K members). Focuses on builders sharing workflows.

**@steipete status:** Joined OpenAI Feb 15, 2026. Likely less active on community projects now. OpenClaw continues as foundation. Tag @openclaw, not @steipete for community amplification.

**What they care about:** Technical demos, security tooling, "AI can now do X" framing.

**Format:** Short thread with GIF demo. Technical hook first.

**Ideal tweet:**
> clavitor: a local password vault built for AI agents.
>
> Your @OpenClaw agent calls clavitor_get("GitHub PAT") via MCP. No cloud. No subscription. Two-tier encryption — L1 for AI, L2 for your eyes only.
>
> clawhub install clavitor 🦞🔐

---

### Channel 5: awesome-openclaw-skills — `github.com/VoltAgent/awesome-openclaw-skills`

Most-browsed curated skill list (5,400+ indexed). Submit PR to add entry under Security/Credentials category. Short description + install command. High passive discoverability.

---

### Channel 6: awesome-openclaw — `github.com/SamurAIGPT/awesome-openclaw`

General awesome-list for OpenClaw resources. Submit PR under "Tools" or "Security" category.

---

### Timing Note

Peter Steinberger joined OpenAI Feb 15, 2026 — OpenClaw is now a foundation, "open, independent, and just getting started." Community is in a transition moment — good time to contribute substantive tools and get noticed by the foundation team running community/marketing.

---

### Priority Order for Announcement

1. **ClawHub PR** — gets it discoverable via `clawhub install clavitor`; required for all else
2. **GitHub Discussions** — technical audience, high quality signal
3. **Discord** — fastest community feedback loop
4. **X @openclaw** — broadest reach if amplified
5. **awesome-openclaw-skills PR** — passive long-tail discoverability
6. **awesome-openclaw PR** — supplementary

---

*End of RESEARCH.md*