Log a code change
log_changeRecord a codebase change with entity path, type, diff, and reasoning. Each event is stored locally with a timestamp and validated, returning warnings if reasoning is generic.
Instructions
Record a change to a codebase entity.
Call this immediately after making any meaningful change. The event is
written to the local SQLite store and returned with its assigned id and
timestamp. If the reasoning fails the quality validator (empty, too
short, or a generic placeholder), the result includes a warnings
array — the event is still stored.
On validation failure (invalid change_type, missing entity_path) the
result is {"status": "error", "error": "..."} with no event written.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_path | Yes | Dot/slash-notation path to the entity. Required and non-empty. Examples: 'users.email' (DB column), 'users' (DB table), 'src/auth.py::login' (function in file), 'src/auth.py' (file), 'api/v1/users' (API route), 'deps/stripe' (dependency), 'env/STRIPE_SECRET_KEY' (env variable). | |
| change_type | Yes | What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate. Invalid values are rejected — pick the closest match. | |
| diff | No | The actual change — SQL migration text, code diff, or a human-readable description of what changed. Optional but strongly recommended for non-trivial changes. | |
| entity_type | No | Category of entity. One of: column, table, file, function, class, endpoint, dependency, env_var, index, schema, config, other. Unknown values are coerced to 'other'. | other |
| reasoning | No | Why the change was made. Include the user's original request, the problem being solved, or any context that won't be obvious from the diff alone. Good example: 'User asked to add 2FA — needs phone number to send SMS verification codes.' Avoid generic placeholders like 'user request' or 'done' — these are flagged by the quality validator and returned in `warnings`. | |
| agent | No | Name/ID of the AI agent making the change (e.g. 'claude-code', 'cursor', 'copilot', 'human'). | |
| session_id | No | The agent session or conversation ID, if available. | |
| git_commit | No | The git commit hash this change will land in. Can be backfilled later via `selvedge backfill-commit` or the post-commit hook. | |
| project | No | Repository or project name. Useful when one DB tracks multiple projects. | |
| changeset_id | No | Optional grouping ID for related changes that belong to the same feature or task. Use a short slug like 'add-stripe-billing'. All events sharing a changeset_id can be queried together via the `changeset` tool. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| timestamp | Yes | ||
| status | Yes | ||
| error | Yes | ||
| warnings | Yes |