selvedge 0.2.0

Change tracking for AI-era codebases

Selvedge

Change tracking for AI-era codebases.

---

Six months ago, your AI agent added a column called user_tier_v2. You don't know why. Git blame points to a commit message that says "Update schema." The agent session that made the change is long gone.

With Selvedge, you run this instead:

$ selvedge blame user_tier_v2

  user_tier_v2
  Changed     2025-10-14 09:31:02
  Agent       claude-code
  Commit      3e7a991
  Reasoning   User asked to add a grandfathering flag for legacy free-tier
              users during the pricing migration. Stores the original tier
              so we can backfill discounts without touching billing history.

That reasoning came from the original request — captured by the agent in the moment, before the session ended.

---

---

The problem

Human-written code leaks intent everywhere — commit messages, PR descriptions, inline comments. AI-written code doesn't. The agent knows exactly why it made each decision, but that context lives in the prompt and evaporates when the conversation ends.

Six months later, your team is debugging a schema decision with no trail. git blame tells you what changed and when. It can't tell you why.

Selvedge captures the why.

---

Install

pip install selvedge

Quickstart

1. Initialize in your project

cd your-project
selvedge init

2. Add to your Claude Code config

~/.claude/config.json:

{
  "mcpServers": {
    "selvedge": {
      "command": "selvedge-server"
    }
  }
}

3. Tell your agent to use it

Add to your project's CLAUDE.md:

You have access to Selvedge for change tracking.
Call selvedge.log_change immediately after adding, modifying, or removing
any DB column, table, function, API endpoint, dependency, or env variable.
Set `reasoning` to the user's original request or the problem being solved.
Set `agent` to "claude-code".
Before modifying an entity, call selvedge.blame to understand its history.

4. Query your history

selvedge status                        # recent activity
selvedge diff users                    # all changes to the users table
selvedge diff users.email              # changes to a specific column
selvedge blame payments.amount         # what changed last and why
selvedge history --since 30d           # last 30 days of changes
selvedge search "stripe"               # full-text search
selvedge stats                         # log_change coverage report
selvedge install-hook                  # auto-link commits to events
selvedge import migrations/            # backfill from migration files
selvedge export --format csv           # dump history to CSV

---

How it works

Selvedge runs as an MCP server. AI agents in tools like Claude Code call Selvedge's tools as they work — logging structured change events to a local SQLite database.

Each event records:

• What changed (entity path, change type, diff)
• When (timestamp)
• Who (agent, session ID)
• Why (reasoning — captured from the agent's context in the moment)
• Where (git commit, project)

The diff is git's job. The why is Selvedge's.

---

Entity path conventions

users.email           DB column (table.column)
users                 DB table
src/auth.py::login    Function in a file (path::symbol)
src/auth.py           File
api/v1/users          API route
deps/stripe           Dependency
env/STRIPE_SECRET_KEY Environment variable

Prefix queries work everywhere: users returns users, users.email, users.created_at, and any other entity under the users. namespace.

---

MCP tools

When connected as an MCP server, Selvedge exposes:

Tool	Description
log_change	Record a change event with entity, diff, and reasoning
diff	History for an entity or entity prefix
blame	Most recent change + context for an exact entity
history	Filtered history across all entities
search	Full-text search across all events

---

CLI reference

selvedge init [--path PATH]               Initialize in project
selvedge status                           Recent activity summary
selvedge diff ENTITY [--limit N]          Change history for entity
selvedge blame ENTITY                     Most recent change + context
selvedge history [--since SINCE]          Browse all history
              [--entity ENTITY]
              [--project PROJECT]
              [--limit N]
selvedge search QUERY [--limit N]         Full-text search
selvedge stats [--since SINCE]            Tool call coverage report
selvedge install-hook [--path PATH]       Install git post-commit hook
selvedge backfill-commit --hash HASH      Backfill git_commit on recent events
selvedge import PATH                      Import migration files (SQL / Alembic)
              [--format auto|sql|alembic]
              [--project NAME]
              [--dry-run]
selvedge export [--format json|csv]       Export history to JSON or CSV
              [--since SINCE]
              [--entity ENTITY]
              [--output FILE]
selvedge log ENTITY CHANGE_TYPE           Manually log a change
             [--diff TEXT]
             [--reasoning TEXT]
             [--agent NAME]
             [--commit HASH]
             [--project NAME]

All read commands support --json for machine-readable output.

Relative time in --since:

• 7d → last 7 days
• 24h → last 24 hours
• 3m → last 3 months
• 1y → last year

---

Configuration

Method	Format	Example
Env var	SELVEDGE_DB=/path/to/db	Per-session override
Project init	selvedge init	Creates .selvedge/selvedge.db in CWD
Global fallback	~/.selvedge/selvedge.db	Used if no project DB found

---

Coverage checking

Wondering how often your agent actually calls log_change? Two ways to check:

# Quick summary in the terminal
selvedge stats

# Cross-reference against git commits
python scripts/coverage_check.py --since 30d

The coverage script compares your git log against Selvedge events and shows which commits have associated change events. Low coverage usually means the system prompt needs strengthening — see docs/fallbacks.md for guidance.

---

Contributing

git clone https://github.com/masondelan/selvedge
cd selvedge
pip install -e ".[dev]"
pytest

See CLAUDE.md for architecture details and the phase roadmap.

---

License

MIT — see LICENSE.