# Codevira v2.2.0 — Pre-ship Audit (2026-05-22)

> Purpose: before shipping v2.2.0, honestly map the 5 user complaints
> from churned users against what v2.2.0 actually fixes, what it
> doesn't, and what the data tells us about the product hypothesis.
>
> Audience: Sachin (founder). Brutal cofounder mode. No defensive
> framing.
>
> Status: **Draft.** Audit collected 2026-05-22 within Claude Code
> session by reading ~/.claude.json, backup graph.dbs from
> ~/.codevira.WIPED-2026-05-22.bak, and grepping the v2.2.0 codebase
> for system-write locations.

---

## Finding 1 — Adoption pattern (the load-bearing finding)

### Data

From `~/.claude.json`, the founder's own Claude Code session history
over the last 30 days:

| Date | Project | First prompt |
|---|---|---|
| 2026-05-15 | lh-interface | **"using codevira** get roadmap" |
| 2026-05-14 | UDAP | **"using codevira** whas the roadmap" |
| 2026-05-13 | AgentStore | **"using codevira** can you give me the roadmap" |
| 2026-05-04 | agent-mcp | "do you know what we are doing?" *(self-dev)* |

**3 of 3** user-of-codevira sessions had to **explicitly invoke
codevira** in the first prompt. All 3 were **read requests** ("get
roadmap"). Zero auto-recording activity. Zero historical decisions
preserved in any data backup.

### Interpretation

- The founder cannot get codevira to fire without prompt-engineering
  the invocation each session.
- All 3 uses were as a **read-side lookup tool** (roadmap query), not
  as an auto-recording memory layer.
- The "AI auto-pulls context" assumption that v2.2.0 (and v2.1.x) is
  built around does not match real founder usage.

### Implication

Either:

1. **The AI cannot be trained reliably** to call codevira tools
   without explicit user prompting (CLAUDE.md / AGENTS.md nudges
   aren't strong enough). If true, fixing this requires either
   sub-agents (Claude Code agents) or PostToolUse hooks that
   force-record. Both are Claude-Code-specific.
2. **Or the product shape is wrong.** Maybe codevira should be a
   user-invoked slash-command surface rather than an autonomous
   memory layer.

Either fork rewrites a substantial portion of v2.2.0's design.

---

## Finding 2 — Competitive grid (honest per-pain comparison)

For each pain that brought users to codevira, who actually wins today?

| Pain | Claude Code `--continue` | Cursor `.cursorrules` | AGENTS.md (manual) | mem0 / agentmemory | Codevira |
|---|---|---|---|---|---|
| Single-IDE memory across sessions | ✓✓ built-in, free, automatic | ✓ if rules updated | ✓ if maintained | ✓ if AI calls SDK | ✓ if AI calls record_decision (it doesn't) |
| Cross-IDE memory | ✗ Claude Code only | ✗ Cursor only | ✓ 10+ IDEs read natively | ✓ via per-tool SDK | ✓ via AGENTS.md + MCP |
| Team coordination | ✗ per-machine | ✓ committed to repo | ✓ committed to repo | ✗ cloud/per-machine | ⚠ committed but **merge-conflict-prone** |
| Decision enforcement (block AI edits that violate prior choice) | ✗ no enforcement | ✗ soft prompt | ✗ soft prompt | ✗ recall-only | **✓ UNIQUE** (PreToolUse hook hard-blocks) |
| Code-structure context (callers, blast radius) | ✗ | ✗ | ✗ | ✗ | ✓ (SQLite graph) |
| Setup friction | none | none | none | low | **high** (8 IDE configs, hooks, doctor) |
| Install size | 0 MB | 0 MB | 0 MB | ~5-30 MB | **71 MB** (v2.2.0; was 450 MB) |

### Where codevira **uniquely** wins

1. **Hard decision enforcement** (PreToolUse hook blocks edits
   violating `do_not_revert`). Nobody else does this.
2. **Code graph + decisions in one tool**. Code-review-graph does
   the graph; mem0 does the memory. Codevira does both.

### Where codevira **loses**

1. **Single-IDE memory**: Claude Code's `--continue` covers it free
   and automatically. No reason to install codevira if you only use
   Claude Code.
2. **Cross-IDE memory** (the marketing wedge): AGENTS.md (just a
   markdown file, manually maintained) achieves it for free. Codevira
   auto-generates AGENTS.md, which is genuinely a value-add — but
   the value-add is the **generation**, not the cross-IDE part.
3. **Team coordination**: Cursor rules + AGENTS.md beat codevira on
   merge-conflict avoidance. Codevira's monotonic IDs actively
   create conflicts.
4. **Simplicity**: every competitor is simpler. mem0 is one SDK call.
   AGENTS.md is one file. Codevira is 33 MCP tools + 19 CLI commands
   + 8 IDE integrations.

### Honest assessment

**Codevira's defensible wedge is decision enforcement.** Everything
else is matched or beaten by a simpler alternative.

But — per Finding 1 — the founder has never **used** decision
enforcement (zero `do_not_revert=True` decisions in any backup).
The unique wedge is academic, not field-validated.

---

## Finding 3 — Surface area (uninstall inventory)

What `codevira init` + `codevira setup` writes to your system:

### Per-user (machine-wide)
- `~/.codevira/` (data dir; survives uninstall)
  - `~/.codevira/global.db` (cross-project SQLite)
  - `~/.codevira/logs/crashes.log`
  - `~/.codevira/projects/<key>/` (legacy v2.1.x layout, still created in some paths)

### IDE configs (per detected IDE)
- `~/.claude.json` — MCP entry injected
- `~/.claude/hooks/codevira-*.sh` — per-event hook scripts
- `~/.cursor/mcp.json` or `~/.cursor/mcp_settings.json`
- `~/.windsurf/mcp_config.json` or `~/.codeium/windsurf/mcp_config.json`
- `~/.gemini/antigravity/mcp_config.json` (Google Antigravity)
- `~/.codex/config.toml` (OpenAI Codex CLI)

### Per-project (added to your repo)
- `<repo>/.codevira/` — JSONL storage (committed)
- `<repo>/.codevira-cache/` — gitignored, rebuildable
- `<repo>/AGENTS.md` — codevira marker block added
- `<repo>/CLAUDE.md` — duplicate marker block
- `<repo>/GEMINI.md` — duplicate marker block
- `<repo>/.cursor/rules/codevira.mdc` — Cursor-specific nudge
- `<repo>/.windsurfrules` — Windsurf-specific nudge
- `<repo>/.github/copilot-instructions.md` — Copilot-specific nudge
- `<repo>/.gitignore` — modified to ignore `.codevira-cache/`

### Tally
- **~6 system-wide locations** modified per `codevira setup`
- **~9 per-project locations** modified per `codevira init`
- **Total touch points on a setup+init**: ~15 files/dirs across the system
- **`codevira uninstall` command**: does not exist
- **`pipx uninstall codevira`**: removes the venv only; **leaves all 15
  touch points behind**

### Implication

"Polluting my system" and "uninstall left junk" complaints are
**100% accurate** — the surface area is structurally sprawling, and
there's no cleanup path. Users who try codevira and bounce leave
debris that confirms their bad opinion.

---

## Finding 4 — What v2.2.0 actually addresses

Mapping the 5 user complaints to v2.2.0's actual deliverables:

| Complaint | Sub-issue | v2.2.0 status |
|---|---|---|
| Install / setup | Took forever | ✓ **FIXED** (71 MB, <100ms startup) |
| Install / setup | Polluted my system | ✗ NOT FIXED — 15 touch points remain |
| Install / setup | Uninstalling left junk | ✗ NOT FIXED — no `codevira uninstall` |
| Install / setup | Too complicated | ✗ NOT FIXED — 33 tools, 19 commands |
| First-day experience | "Didn't see what it does" | ✗ NOT FIXED — no demo flow |
| First-day experience | "AI didn't call codevira tools unless asked" | ✗ NOT FIXED — adoption gap untouched |
| Reliability | Broke after IDE update | ✗ STRUCTURALLY NOT FIXED — 8-IDE surface |
| Reliability | Crashed | ✓ partial — chromadb/torch causes gone |
| Reliability | Ate my disk | ✓ FIXED — 64GB HNSW class impossible |
| Team usage | Merge conflicts on decisions.jsonl | ✗ **MADE WORSE** — chose JSONL design |
| Compete-against | Cursor / mem0 / `--continue` simpler | ✗ NOT FIXED — no positioning shift |

**v2.2.0 wins: 3 (install size, crash safety, disk explosion).**
**v2.2.0 misses: 8** (4 critical: adoption gap, system pollution,
team conflicts, no uninstall).

The wins are **invisible to users** (they don't notice install size
unless they're sysadmins; they don't notice "crashes that didn't
happen"; they don't notice "disk that didn't explode").

The misses are **felt** (they show up every session).

---

## Strategic options for v2.2.0

Three honest paths forward:

### Option A — Cut to a slash-command product (~2 weeks)

Match the founder's actual usage pattern. Drop the auto-memory frame.

- Replace `codevira init`/`setup` with a single Claude Code
  `/codevira` slash command + sub-agent install. One command, one
  IDE, one config file modified.
- The sub-agent exposes: `/codevira roadmap`, `/codevira context`,
  `/codevira decisions <topic>`, `/codevira record <decision>`,
  `/codevira fixes`. User-invoked, deterministic, no "did the AI
  call my tool?" risk.
- Drop 28 of 33 MCP tools. Drop 8-IDE setup. Drop hooks (or keep
  only the do_not_revert PreToolUse). Drop nudge file generation
  (just AGENTS.md, optionally).
- Pitch: **"The /codevira slash command. Project-scoped roadmap,
  decisions, code graph. One command per query."**
- Loses: the "passive memory" claim (which never worked anyway).
- Wins: shippable in 2 weeks, easy to demo, matches user pattern,
  uninstall is trivial.

### Option B — Force adoption with hooks + sub-agents (~4-6 weeks)

Believe the AI CAN be made to auto-call codevira if instrumented
hard enough.

- Build a PostToolUse hook that force-records every Edit/Write
  with metadata: "AI just modified `auth.py` at session `s1`".
  Decisions accumulate without AI cooperation.
- Build a SessionStart hook that auto-injects relevant decisions
  (already done by RelevanceInject).
- Ship a "codevira sub-agent" via Claude Code agents that the user
  invokes once — `/codevira-mode on` — and from then on, the agent
  takes over all codevira interactions.
- Loses: 4-6 weeks of work. Claude-Code-first (other IDEs degrade).
  Risk of force-records creating noise.
- Wins: if it works, codevira becomes the first truly passive
  memory layer.

### Option C — Pivot to "the AGENTS.md generator" (~1-2 weeks)

Drop the "memory" frame. Position codevira as plumbing.

- Pitch: **"Auto-updates your AGENTS.md as your team's AI sessions
  produce decisions. Every other AI tool reads AGENTS.md natively."**
- Surface is small: `codevira init`, `codevira record-decision`,
  `codevira sync`. Maybe 5 commands.
- Drop hooks, drop the inject path, drop the code graph (or move
  it to a separate `codevira-graph` package).
- Wins: clear value prop ("the AGENTS.md tool"). Compatible with
  every IDE. Doesn't depend on AI cooperation.
- Loses: the unique enforcement wedge.

### Option D — Don't ship v2.2.0. Talk to 5 ex-users first.

Customer-dev for 1-2 weeks. Confirm which of A/B/C is right (or
discover a fourth path). Only then ship.

---

## Recommendation

I lean **Option A** based on the audit data:

1. The founder's actual usage IS slash-command-shaped (3/3 sessions).
2. The "AI auto-calls tools" hypothesis has zero supporting evidence
   in the data.
3. Option A is the smallest credible product that ships fast.
4. If A succeeds in retention, B and C are unnecessary. If A fails,
   we have data to know which way to pivot.

But this is a strategic call, not a technical one. The decision is
the founder's.

---

## What this audit does NOT tell us

- Verbatim complaints from the 100s of ex-users (we have categories,
  not transcripts). Customer-dev would surface the actual words.
- How a 100-developer team would experience merge conflicts in
  practice. Synthetic; needs simulation or pilot.
- Whether the slash-command pivot would actually retain users.
  Needs real-user testing.
- Whether `do_not_revert` enforcement matters once a user IS using
  the product. Field unknown.
