Chronon

Chronon is local version control for text documents that AI agents edit, especially Markdown. Every file gets its own linear, immutable history, and every commit carries a message explaining why it changed. It works alongside Git but neither calls nor replaces it.

• Vault: a named collection of managed files, such as knowledge or research. People and agents refer to it by name from any directory.
• People use the chronon CLI.
• Agents follow a generated CHRONON.md and use the chronon-mcp server (recommended) or the CLI. They never edit vault files directly.

Status: alpha. Manual commit mode only. Chronon history is local and not pushed with Git, so see Data and backups.

Install

Requires Python 3.11+ on macOS, Linux, WSL2, or Windows.

uv tool install chronon-vcs   # or: pipx install chronon-vcs

See docs/installation.md for GitHub tags, platform setup, and uninstalling.

Quick start

Create and register a vault:

mkdir -p ~/Documents/knowledge
chronon init ~/Documents/knowledge --register knowledge

Use it yourself

chronon -v knowledge write first-note.md --content 'The pilot launches in October.' -m "add first note"
chronon -v knowledge read first-note.md
chronon -v knowledge log first-note.md

Editing, diffs, and recovery are covered in the CLI guide.

Let an agent use it

In the workspace where you run your agent (it does not need to be the vault):

chronon agent-setup --vault knowledge
claude mcp add --transport stdio chronon -- "$(command -v chronon-mcp)"
# Codex: codex mcp add chronon -- "$(command -v chronon-mcp)"

Then ask in plain language. There is no need to mention Chronon:

Save these meeting notes in the knowledge vault as meeting-notes.md:
The pilot launches in October. Mina owns testing; Jae owns documentation.

Skip the MCP step and the agent falls back to the CLI. Re-run agent-setup after upgrading Chronon to refresh the guidance.

How it works

• One file, one history. Commits are per file, need a message, and are never rewritten. rollback adds a new commit.
• Safe concurrent edits. Writes take the last-read working_revision (--if-match / expected_revision) and fail if the file changed since.
• Outside edits are caught. A change made in a normal editor shows up as foreign and is neither lost nor silently accepted.
• Structured diffs. YAML and JSON diff by value, and set / path-history work on individual keys. Optional JSON Schema validation runs before each write.
• Time-based lookup. Revisions can be 3, latest~2, 2026-08-01, or 7d ago.

Documentation

• CLI guide: editing workflow, file states, revisions, vault registry, command reference
• Agents and MCP: agent-setup, permissions, MCP configuration, and expected agent behavior
• Installation
• Contributing: development setup and tests

Data and backups

History lives in each vault's .chronon/ directory, which Chronon adds to .gitignore. It is not pushed with Git. Back up the working files and .chronon/ together. Content is not encrypted. Writes are atomic and locked across processes, but there is no multi-file transaction.

License

MIT