Frequently asked

# Questions, answered.

The questions people actually ask after reading the README. If yours isn't here, open an issue.

Isn't this just git blame?
No. `git blame` tells you what changed and when. It can't tell you why — especially when the committer is an AI agent and the commit message is auto-generated. Selvedge captures the agent's own reasoning live, in the moment, and attaches it to entities (a column, an env var, an endpoint) rather than line numbers.
Why not just rely on commit messages?
Commit messages are written about a whole diff, after the fact. Selvedge captures per-entity reasoning while the agent still has the prompt context. One commit can have ten Selvedge events, each with different reasoning. AI-generated commit messages are also notoriously generic — most of the original intent never makes it into the commit.
How is Selvedge different from AgentDiff, Origin, Git AI, or BlamePrompt?
Two ways. (1) AgentDiff, Origin, Git AI, and BlamePrompt infer reasoning post-hoc, by feeding the diff to a second LLM at commit time. Selvedge captures the agent's own intent live, from the same context window. (2) Those tools attribute lines. Selvedge attributes entities — the column, the env var, the route — which is what people actually search for. See the comparison page for details.
What does Selvedge cost?
Free. MIT licensed. No SaaS, no telemetry, no account. Install with `pip install selvedge`.
Where does my data live? Does anything leave my machine?
Nowhere. The data is in a SQLite file under `.selvedge/` in your project. Zero network calls, zero telemetry. The MCP server runs locally as a subprocess of your AI tool. You can `cat` the SQLite file and see every row.
What if my AI agent doesn't actually call Selvedge?
Coverage is the real problem, not capture quality. Two answers. (1) `selvedge prompt` prints a system-prompt block that strongly nudges the agent to log changes. (2) `selvedge stats` and `scripts/coverage_check.py` tell you exactly what your call ratio is per commit, so you know when the prompt needs strengthening. An empty `reasoning` field is itself a useful signal — it means the agent didn't have explicit intent for that change.
Does Selvedge work with Claude Code, Cursor, and Copilot?
Yes — all three. `selvedge setup` detects which AI tools you have and configures all of them in one pass: writes the MCP entry into each tool's config, drops the canonical agent-instructions block into the right prompt file (`CLAUDE.md` / `.cursorrules` / `copilot-instructions.md`), and installs the post-commit hook.
What is a changeset?
Imagine you're rolling out Stripe billing. It touches the `users` table, two new env vars, three API routes, one dependency, and four functions across the codebase. Tag every event with `changeset:add-stripe-billing` and `selvedge changeset add-stripe-billing` pulls the entire scope back later — even if the work was broken into eight smaller PRs over a month. It's the rollup view for cross-cutting features.
Can I use Selvedge on an existing codebase?
Yes. From the moment you install it, every new agent change is captured. For retroactive coverage, `selvedge import migrations/` backfills history from existing SQL DDL or Alembic migration files.
Is Selvedge production-ready?
The core (capture, query, blame, changesets) is solid — v0.3.x has been hardened with adversarial tests, concurrency tests, and a frozen public API. 282 tests pass across Python 3.10–3.13 and SQLite 3.37–3.45. Phase 3 work (team sync, Postgres backend) isn't shipped yet. For single-developer use today: yes. For team rollout: yes if your team is fine sharing the SQLite file or each developer keeps their own.
How long does Selvedge take to set up?
About 90 seconds. `pip install selvedge`, `cd` into your project, then `selvedge setup`. The wizard detects your AI tools and configures everything in one pass. Every modified file gets a `.bak` backup before any change reaches disk.
How do I uninstall Selvedge?
`rm -rf .selvedge/`, remove the MCP entry from your AI tool config, then `pip uninstall selvedge`. Done. Nothing leaks anywhere.
What's Selvedge's relationship to Agent Trace?
Agent Trace is an emerging open standard for AI code attribution traces (Cursor + Cognition AI's RFC, backed by Cloudflare, Vercel, Google Jules, and others). Selvedge isn't competing with it — Selvedge is a compatible producer. Agent Trace is the wire format; Selvedge is the live capture and query layer that emits it. The design for `selvedge export --format agent-trace` ships in v0.4.0.
Is there a hosted version?
Not yet. The local tool is and will always be free, MIT, and local-only. A hosted team-sync layer is on the long-term roadmap (Phase 3) but isn't shipped. The data stays in SQLite on your disk; you own it.

Try it in 90 seconds

pip install selvedge && selvedge setup