Git for the config living in your database.

Version, diff, and roll back the rows that drive your app, without moving them out of Mongo or Postgres.

Feature flags, agent configs, model routing, thresholds: the config people edit straight in prod. A clean tool for dirty workflows.

Quickstart

Or let your coding agent do it

Add to Cursor Agent docs →

Apache-2.0

cfgit UI showing drift review, history, and a line-aligned diff between recorded and live

cfgit UI showing system impact analysis with changed paths, categories, and affected records

cfgit UI showing scoped impact analysis reasoned against selected related records

cfgit UI showing branches: main, a draft branch, and an open pull-request branch with compare

cfgit UI showing a pull request diff between main and a feature branch with field changes

Try it interactive →

The diff between what cfgit recorded and what is live in the database right now.

The problem

People and agents change your app's behavior by editing rows straight in the database. No diff, no history, no undo.

The catch

You can't put that config in git without moving it out of your database. So nobody does.

What cfgit does

Adds versions, diffs, drift detection, and rollback around those rows, in place.

Quickstart

try it against a dev datastore

About 5 minutes against a local or staging database. A change made straight in the DB becomes a diff you can see and adopt, not a 2am incident.

00

install

pip install 'cfgit[mongo,postgres,mcp]'. Extras pick adapters.

01

configure

Add a .cfg.toml with your collection, id field, and env URI.

02

initialize

Run doctor, init history, import live records as the first head.

03

inspect

Run status and diff to see if the live DB drifted from history.

04

operate

status, diff, adopt, commit, restore, or the local UI.

dev setupMongo example

$ pip install 'cfgit[mongo,postgres,mcp]'

$ cat > .cfg.toml <<'TOML'
[project]
name = "runtime-control-plane"

[history]
history_collection = "config_history"
heads_collection = "config_heads"

[[collection]]
name = "agent_configs"
id_field = "config_id"
live_when = { is_active = true }
ignore_fields = ["_id", "is_active", "updated_at"]
secret_fields = []

[env.dev]
database = "mongo"
uri = "env:DEV_MONGODB_URI"
db = "my-dev-db"
needs_approval = false

[env.dev.identity]
mode = "open"

[env.dev.permissions]
mode = "open"
TOML

$ export DEV_MONGODB_URI='mongodb://localhost:27017/?replicaSet=rs0'
$ cfg init
$ cfg doctor
$ cfg import --all -m "initial import"
$ cfg status
$ cfg diff agent_configs:planner =HEAD =live
$ cfg adopt agent_configs:planner -m "adopt admin edit"
$ cfg commit agent_configs:planner --from planner.json -m "tune planner"
$ cfg ui

Workflow

track live records without owning the store

The interesting state is drift. Someone bumps the planner model in Mongo to unblock a demo, tells no one, and cfgit shows you exactly that diff instead of leaving you bisecting prod at midnight.

status flags drift, adopt folds it into history, and every write checks the live value first.

operator flowdirty store

$ cfg status
agent_configs:planner changed_outside_cfgit

$ cfg diff agent_configs:planner =HEAD =live
  provider.model: gpt-4.1 -> gemini-2.5-pro
  retry.max: 2 -> 4

$ cfg adopt agent_configs:planner -m "record hotfix"
adopted @12

$ cfg commit agent_configs:planner --from planner.json -m "tune planner"
committed @13

01

live record

The app keeps reading the same collection. cfgit never moves the runtime path.

02

recorded head

History keeps full JSON versions with stable content hashes.

03

drift check

Status compares live hash to head hash, marks out-of-band edits dirty.

04

adopt or stop

Bypassed changes become history, or commits refuse to overwrite them.

What shipped

engine, adapters, CLI, UI, MCP

One engine does the careful part. The CLI, UI, and agent tools all get the same guarantees.

status / diff / log

record history

Versioned JSON records with readable diffs, tags, show, restore, import, and system restore.

write checks

drift guard

Catches changes made straight in the DB and refuses to clobber them. Nothing gets silently overwritten.

storage adapters

Mongo and Postgres

The core imports no database drivers. Adapters implement the storage contract per datastore.

local ui

web UI

A localhost UI to browse history, diffs, adopt, and restore by clicking.

mcp tools

agent-safe

Let an agent edit config through MCP, and every change is versioned, diffable, and revertable like any other.

branch / pr

branches and PRs

Opt-in branches and pull requests for draft changes. Diff main..branch, then merge.

identity / secrets

guardrails

Per-env identity, an optional approval gate, and secrets stripped before they hit history.

impact plugin

impact preview

See what a change touches before you commit it. Optional plugin, core stays provider-free.

Architecture

shared action layer

Four layers, one operation envelope. Storage is swappable; the core imports no DB drivers and no LLM providers.

interfaces

CLI commands, JSON output, localhost UI, MCP tools, and portable agent instructions route through one operation envelope.

core engine

Opaque JSON records, canonical hashing, diffing, status, commit, adopt, tag, restore, branch refs, identity checks, and secret checks.

storage

MongoDB and Postgres adapters implement the storage contract and expose only the guarantees each store can back.

plugin boundary

cfgit-impact owns deterministic impact summaries and optional LLM narration. The core stays provider-free.

Agents

set it up with your coding agent

cfgit ships a Claude Code / Codex skill, an cfg-mcp MCP server, and portable agent instructions. Humans and agents use the same operation surface, so an agent can inspect, diff, and version config with the same guardrails you get.

1. Point your agent at cfgit

paste into Claude Code, Codex, or Cursor

Set up cfgit in this repo. Install it (pip install 'cfgit[mongo,postgres,mcp]'),
create a .cfg.toml pointing at my dev/staging database, install the cfgit skill
and the cfg-mcp MCP server, then run cfg doctor and cfg import --all to record
the current config as history. Docs are at github.com/AusafMo/cfgit. Never write
to prod or use cross-project DB URIs without asking me first.

2. Or wire it manually

MCP server + skill

$ pip install 'cfgit[mongo,postgres,mcp]'
$ cfg-mcp                          # run the MCP server your agent connects to
# drop skills/cfgit/SKILL.md into your agent's skills, or point it at docs/AGENTS.md

The flow an agent follows

01

status

The agent runs cfg_status to see what drifted before touching anything.

02

diff + impact

cfg_diff then cfg_impact on any behavior-affecting record before it commits.

03

commit or adopt

Mutates through cfgit, never a raw DB write, so history and rollback stay coherent.

04

guardrails

It never commits over drift, and it can't write prod or cross-project without your say-so.

put your live config under version control

View repo