backend tool / 2026

cfgit

Version history, diffs, drift checks, adoption, and restore for records that stay in MongoDB or Postgres.

View repo Quickstart

Python package MongoDB + Postgres CLI + UI + MCP Apache-2.0

Problem

Runtime behavior is often edited through database rows, documents, scripts, dashboards, and agents.

Constraint

The application keeps its current datastore. cfgit stays beside it.

Move

Record versions, detect drift, adopt external changes, and block stale writes.

Quickstart

try it against a dev datastore

Start with a local or staging database. cfgit stores history beside the live records and checks drift before writes.

01

configure

Create .cfg.toml with the collection, id field, ignored fields, and environment URI.

02

initialize

Run doctor, initialize cfgit history, and import the current live records as the first head.

03

inspect

Use status and diff to see whether the live database has drifted from recorded history.

04

operate

Use status, diff, adopt, commit, restore, or the local UI over the same action layer.

dev setupMongo example

$ 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

cfgit records versions beside existing MongoDB or Postgres data. The application still reads and writes the original datastore.

Status compares the live record with the recorded head. If they diverge, cfgit marks drift instead of allowing a stale commit.

cfg adopt turns an out-of-band change into history. Commit and restore check the current live value before writing.

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 application keeps reading the same collection or table. cfgit does not move the runtime path.

02

recorded head

History stores full JSON versions with stable content hashes and sequence numbers.

03

drift check

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

04

adopt or stop

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

What shipped

engine, adapters, CLI, UI, MCP

The core owns hashing, diffs, drift checks, restore planning, and write guards. Interfaces call the same action layer.

status / diff / log

record history

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

write checks

drift guard

Commit and restore compare expected head and live values before mutating the datastore.

storage adapters

Mongo and Postgres

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

local ui

operator view

The localhost UI shows state, history, branch controls, diffs, adoption, and restore.

mcp tools

agent tools

MCP tools use the same action layer and return structured envelopes for inspection and mutation.

impact plugin

optional impact

Impact analysis stays outside core, with provider code and LLM narration isolated in a plugin.

Screens

localhost UI

The UI exposes collection state, history, diffs, adoption, restore, and optional impact analysis.

cfgit UI showing production-shaped drift review, branch controls, history, and a line-aligned diff — **Drift review** Collection status, recent operations, live drift, and the exact field-level diff before adoption or commit.

cfgit UI showing high-risk system impact narration for a record change — **Impact** Deterministic change analysis with optional provider narration when the record can leave the local boundary.

cfgit UI showing scoped impact analysis across selected related records — **Scoped context** Impact can be scoped to selected policy, eval, and rollout records instead of a broad system map.

Architecture

shared action layer

Correctness stays in the engine. CLI, UI, MCP, and portable agent instructions call the same operations.

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.

history without moving the datastore

cfgit adds history, drift detection, adoption, and restore around records already used by the application.

View repo