Drift – Intent-driven versioning for AI coding agents

Drift, a semantic version-control layer wrapping Git, turns every commit into an 'Intent' that records the originating prompt, agent model, AST-level mutations, an optional cognitive-state checkpoint, and an Ed25519 signature in an auditable, replayable graph. It rejects commits with broken syntax (exit 2), redacts secrets from prompts, and integrates with coding agents such as Claude Code, Cursor, and GitHub Copilot CLI via MCP tools. Verified live on Windows 11 (Node v24.18.0, 2026-08-06), a fresh clone runs first `drift blame` in ~8.1 s with 10/10 checks passing, and the npm path answers the MCP handshake with all six tools in ~1 s.

Git tracks what changed. Drift tracks why. Drift is a semantic version-control layer that wraps Git. Every commit becomes an Intent : the prompt that produced the change, the agent model behind it, the AST-level mutations, an optional checkpoint of the agent's cognitive state, and a cryptographic Ed25519 signature — all linked into an auditable, replayable graph. Built for the AI era. When more than 80% of code is generated, text diffs are useless for review: they show what changed, never why . Drift rejects broken syntax before it enters history, answers "why does this function exist?" with the originating prompt, and lets a crashed agent resume from its last checkpoint. Give your agent Drift: Claude Code claude-code , Antigravity antigravity , Codex App codex-app , Codex CLI codex-cli , Cursor cursor , Factory Droid factory-droid , Gemini CLI gemini-cli , GitHub Copilot CLI github-copilot-cli , Kimi Code kimi-code , OpenCode opencode , Pi pi . Prefer no agent? Use the CLI cli , the GitHub App github-app , the GitHub Action github-action , or VS Code vs-code . Want the 5-minute "aha" first? Seed the demo repo demo and run drift blame . Documentation: Quickstart /lilcipherx/drift/blob/main/docs/quickstart.md 5-minute start · API reference /lilcipherx/drift/blob/main/docs/api.md CLI + MCP tools · Architecture /lilcipherx/drift/blob/main/docs/architecture.md how Drift works under the hood Verified live on Windows 11 Node v24.18.0, 2026-08-06 : fresh clone → first drift blame in ~8.1 s, 10/10 checks pass, no registry 404 — and the npm path packed @drift/ chain installed into an empty dir answers the MCP handshake with all six tools in ~1 s. See the full measured tables /lilcipherx/drift/blob/main/docs/quickstart.md verified-live-%D0%BF%D1%80%D0%BE%D0%B2%D0%B5%D1%80%D0%B5%D0%BD%D0%BE-%D0%B2%D0%B6%D0%B8%D0%B2%D1%83%D1%8E . It starts the moment you run drift init . Drift creates .drift/ — a SQLite DAG, a config, and a per-repo Ed25519 keypair — and from then on every commit becomes an intent. When you or your agent run drift realize -p "<prompt " , Drift doesn't just commit. It parses the change semantically, rejects the commit if the syntax is broken exit 2 — broken code never enters history , redacts secrets from your prompt, computes an AST delta ADDED / MODIFIED / DELETED / MOVED / RENAMED , signs the intent, and stores it content-addressed in .drift/objects/ before committing with a Drift-Intent: trailer. After that, drift blame can walk any line or function back to the prompt that created it, drift context hydrates the last intents for a file so an agent grounds itself before editing, and drift verify re-runs the recorded verification command. A crashed agent runs drift replay --checkout and resumes exactly where it left off. And because these are MCP tools, your coding agent can use them directly — drift realize instead of git commit . Deeper reading: the full command reference lives in docs/api.md /lilcipherx/drift/blob/main/docs/api.md CLI flags, exit codes, JSON schemas, MCP tool inputs , and docs/architecture.md /lilcipherx/drift/blob/main/docs/architecture.md explains the storage model, encryption at rest, the webhook app, and the security boundaries. Installation differs by harness. If you use more than one, install Drift separately for each one. All harnesses expose the same six tools: drift realize , drift context , drift replay , drift blame , drift verify , drift log . Status: theEvery section below leads with the @drift/ npm packages are not published yet.clone path— it works right now from a checkout of this repository. The npx -y @drift/mcp / npx -y @drift/cli one-liners activate automatically once the packages land on npm; until then they return a 404, so use the clone command shown first. Every command below is backed by a real manifest in this repository .claude-plugin/plugin.json , .plugin/plugin.json , .cursor-plugin/plugin.json , .codex-plugin/plugin.json , gemini-extension.json , plugin.json , .factory-plugin/ , package.json → pi or a ready-made config in examples/harness-configs/ . Today, installation needs Node.js ≥ 24, npm and a clone of this repository the MCP server runs straight from packages/drift-mcp/dist/index.js ; no build step needed . Once the @drift/ packages are published, the same configs work via npx -y @drift/mcp with no clone. Install as a plugin from the Drift marketplace plugin-style, like Superpowers : /plugin marketplace add lilcipherx/drift /plugin install drift@drift Or add the Drift MCP server directly project scope — from a clone: claude mcp add drift --env DRIFT REPO=/abs/path/to/your/repo -- node /path/to/drift/packages/drift-mcp/dist/index.js Once the packages are published, the same command works via npx no clone : claude mcp add drift --env DRIFT REPO=/abs/path/to/your/repo -- npx -y @drift/mcp Or copy the ready-made config: cp examples/harness-configs/claude-code/.mcp.json .mcp.json Verify with claude mcp list — you should see drift with its six tools. The marketplace manifest lives at .claude-plugin/marketplace.json in this repository github-source lilcipherx/drift , strict plugin → .claude-plugin/plugin.json in the same repo . Install Drift as a plugin from this repository: agy plugin install https://github.com/lilcipherx/drift Antigravity runs the plugin's session-start hook, so Drift is active from the first message. Reinstall with the same command to update. In the Codex app, open Settings → MCP servers and add: Name : drift Command : node clone path — or npx once the packages are published Args : /path/to/drift/packages/drift-mcp/dist/index.js — or -y @drift/mcp after publication Env : DRIFT REPO=/abs/path/to/your/repo Add the Drift MCP server to ~/.codex/config.toml from a clone : mcp servers.drift command = "node" args = "/path/to/drift/packages/drift-mcp/dist/index.js" env = { DRIFT REPO = "/abs/path/to/your/repo" } Once published, the same server runs via npx no clone : mcp servers.drift command = "npx" args = "-y", "@drift/mcp" env = { DRIFT REPO = "/abs/path/to/your/repo" } Restart Codex, then ask for drift blame / drift context in any session. Copy the ready-made config and enable MCP servers in Cursor settings: cp examples/harness-configs/cursor/mcp.json .cursor/mcp.json Then ask for drift blame in chat. - Register the marketplace: droid plugin marketplace add https://github.com/lilcipherx/drift - Install the plugin: droid plugin install drift@drift - Install the extension: gemini extensions install https://github.com/lilcipherx/drift - Update later: gemini extensions update drift Add the Drift MCP server from a clone : copilot mcp add drift -e DRIFT REPO=/abs/path/to/your/repo -- node /path/to/drift/packages/drift-mcp/dist/index.js Once the packages are published, the same command works via npx no clone : copilot mcp add drift -e DRIFT REPO=/abs/path/to/your/repo -- npx -y @drift/mcp Or copy the ready-made config to .github/mcp.json and restart Copilot. Drift is available in Kimi Code's plugin marketplace. - Open Kimi Code's plugin manager: /plugins - Go to Marketplace Drift and install it. - Or install directly from this repository: /plugins install https://github.com/lilcipherx/drift - Detailed docs: docs/README.kimi.md /lilcipherx/drift/blob/main/docs/README.kimi.md OpenCode uses its own plugin install; install Drift separately even if you already use it in another harness. - Tell OpenCode: Fetch and follow instructions from https://raw.githubusercontent.com/lilcipherx/drift/main/.opencode/INSTALL.md - Detailed docs: docs/README.opencode.md /lilcipherx/drift/blob/main/docs/README.opencode.md Install Drift as a Pi package from this repository: pi install git:github.com/lilcipherx/drift For local development, run Pi with this checkout loaded as a temporary package: pi -e /path/to/drift Add the Drift MCP server to .vscode/mcp.json native VS Code MCP support : cp examples/harness-configs/claude-code/.mcp.json .vscode/mcp.json VS Code picks it up on window reload. From a clone works today : git clone https://github.com/lilcipherx/drift.git && cd drift npm install node packages/drift-cli/dist/cli.js --help Once the CLI is published to npm, npx works without cloning: npx -y @drift/cli --help On your own repository: node /path/to/drift/packages/drift-cli/dist/cli.js init … edit a file … node /path/to/drift/packages/drift-cli/dist/cli.js realize -p "Fix race condition in token refresh" --agent --model claude-3-5-sonnet node /path/to/drift/packages/drift-cli/dist/cli.js log Install @drift/app to get intent summaries on every pull request: - Reads Drift-Intent: trailers from PR commits, hydrates the intent objects from .drift/objects/ at the PR head, and posts a semantic summary comment — review the intent, not 2,000 lines of diff. Comments are idempotent: the app updates its own marker comment in place, so they never accumulate. - Runs as a webhook server: drift-app start see packages/drift-app/app.yml for the app manifest, scripts/webhook-proxy.sh for local debugging . Check intent health in CI: - uses: lilcipherx/drift@v0.3.0 with: command: log or: doctor / verify <intent-id The 5-minute "aha" — a real Drift history, generated by the CLI itself: bash scripts/seed-demo.sh cd examples/demo-repo node ../../packages/drift-cli/dist/cli.js log node ../../packages/drift-cli/dist/cli.js blame src/auth.ts --function refreshToken blame prints the prompt, model and a valid signature for the function: src/auth.ts:12 refreshToken AGENT @ Drift Demo model: claude-3-5-sonnet prompt: Fix race condition in token refresh by de-duplicating in-flight refreshes intent: did 2941b4547b4ed505a7c37190247768a7 commit: 087c492f… signature: valid - init — Creates .drift/ SQLite DAG, config, Ed25519 keypair . Never rewrites history; deleting .drift/ leaves a fully functional git repo. - realize — Commit with intent. Syntax gate exit 2 , secret redaction, AST delta, Ed25519 signature, Drift-Intent: trailer. This is git commit for the AI era. - log — Timeline of intents: id, author agent vs human , model, prompt. - blame / context — blame --line|--function walks a symbol back to its originating prompt; context <file hydrates the last N intents for grounding. - verify — Re-runs the recorded verification command for an intent and checks the Ed25519 signature against the object file never against DB rows . - replay — Restore a checkpointed agent state; --checkout resets the worktree. Crash recovery for agents. - doctor — DAG integrity, signature checks, orphan cleanup, encryption-key check when encryption is enabled. The agent checks the intent before any task. Mandatory for anyone touching generated code. | Package | What it does | |---|---| @drift/cli | The drift CLI — init , realize , log , blame , context , verify , replay , doctor , export | @drift/core | Intent store SQLite DAG , git wrapper, Ed25519 signatures, secret redaction, AES-256-GCM encryption at rest | @drift/ast | Semantic parser TypeScript/JavaScript, Python + AST deltas with a real syntax gate | | Package | What it does | |---|---| @drift/mcp | MCP server — six tools for Claude Code / Codex / Cline, delegates to the CLI | @drift/sdk | Typed SDK + Zod intent schemas | @drift/app | GitHub App — pull request webhook that posts idempotent intent-summary comments | | Package | What it does | |---|---| @drift/action | GitHub Action composite — log / doctor / verify in CI | Semantics over text — diffs show what; intents show why. Always. Broken code never enters history — the syntax gate is the front door. Evidence over claims — every intent is signed; every claim is verifiable. Security by default — secrets redacted, telemetry off, no network calls, optional AES-256-GCM encryption at rest v0.2.0+ . Simplicity — zero native dependencies, strict git compatibility, no rewriting of history. - Every intent is Ed25519-signed ; verification uses the object-file canonical JSON, so signature checks never need the master key. - Prompts are regex-redacted for secrets AWS, OpenAI, GitHub, Slack, JWT, PEM, … before any storage. Encryption at rest v0.2.0 : encryption enabled = true + DRIFT MASTER KEY encrypts prompt and agentState with AES-256-GCM AAD-bound to the intent id . Note: the commit message keeps the plaintext prompt by design PRD §9.1 — see SECURITY.md /lilcipherx/drift/blob/main/SECURITY.md .- Keys are never committed .drift/keys/ is gitignored except throwaway demo keys. The eval harness /lilcipherx/drift/blob/main/eval/harness.mjs PRD §22 drives the real CLI with mock file states — no LLM calls, no network — and records a baseline: npm run eval run scenarios + compare against baseline regression gate npm run eval:record re-record eval/baseline.json Metrics gated at 5% regression PRD §22.3 : syntax-error rejection rate must be 100% , blame accuracy , replay fidelity . Scenarios live in eval/scenarios/ /lilcipherx/drift/blob/main/eval/scenarios . See CONTRIBUTING.md /lilcipherx/drift/blob/main/CONTRIBUTING.md . The general flow: - Fork the repository. - Create a branch for your work. - Keep npm test green 110 tests: unit, temp-git-repo integration, MCP JSON-RPC e2e, GitHub App handler + live webhook-server E2E + client-abort- graceful-shutdown robustness . - Keep the eval baseline green: npm run eval PRD §22 . - Submit a PR using the template. Design decisions are tracked in docs/adrs.md /lilcipherx/drift/blob/main/docs/adrs.md — note that the PRD originally chose Rust ADR-003 ; this implementation ships TypeScript-first ADR-006 for a zero-native-dependency MVS. The drift-ast parser interface is the drop-in point for a future tree-sitter implementation. Once published, MCP servers launched via npx -y @drift/mcp pick up new versions automatically npx always fetches the latest published release . Until then, servers launched from a clone the commands shown in Installation installation track this checkout — update with git pull origin main npm install Releases are tagged on the releases page https://github.com/lilcipherx/drift/releases v0.1.0 , v0.2.0 , v0.2.1 , … . Changelog: CHANGELOG.md /lilcipherx/drift/blob/main/CHANGELOG.md . MIT — see LICENSE /lilcipherx/drift/blob/main/LICENSE . Security notes: SECURITY.md /lilcipherx/drift/blob/main/SECURITY.md . Repository : github.com/lilcipherx/drift https://github.com/lilcipherx/drift Issues : github.com/lilcipherx/drift/issues https://github.com/lilcipherx/drift/issues Releases : github.com/lilcipherx/drift/releases https://github.com/lilcipherx/drift/releases Documentation : quickstart /lilcipherx/drift/blob/main/docs/quickstart.md · API reference /lilcipherx/drift/blob/main/docs/api.md · architecture /lilcipherx/drift/blob/main/docs/architecture.md · examples/demo-repo Code of Conduct : CODE OF CONDUCT.md /lilcipherx/drift/blob/main/CODE OF CONDUCT.md