{"slug": "drift-intent-driven-versioning-for-ai-coding-agents", "title": "Drift – Intent-driven versioning for AI coding agents", "summary": "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.", "body_md": "*Git tracks what changed. Drift tracks why.*\n\nDrift is a semantic version-control layer that wraps Git. Every commit becomes an\n**Intent**: the prompt that produced the change, the agent model behind it, the\nAST-level mutations, an optional checkpoint of the agent's cognitive state, and a\ncryptographic Ed25519 signature — all linked into an auditable, replayable graph.\n\nBuilt for the AI era. When more than 80% of code is generated, text diffs are\nuseless for review: they show *what* changed, never *why*. Drift rejects broken\nsyntax before it enters history, answers *\"why does this function exist?\"* with\nthe originating prompt, and lets a crashed agent resume from its last checkpoint.\n\nGive your agent Drift: [Claude Code](#claude-code), [Antigravity](#antigravity),\n[Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor),\n[Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli),\n[GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code),\n[OpenCode](#opencode), [Pi](#pi).\n\nPrefer no agent? Use the [CLI](#cli), the [GitHub App](#github-app), the\n[GitHub Action](#github-action), or [VS Code](#vs-code). Want the 5-minute \"aha\"\nfirst? Seed the [demo repo](#demo) and run `drift blame`\n\n.\n\n**Documentation:** [Quickstart](/lilcipherx/drift/blob/main/docs/quickstart.md) (5-minute start) ·\n[API reference](/lilcipherx/drift/blob/main/docs/api.md) (CLI + MCP tools) ·\n[Architecture](/lilcipherx/drift/blob/main/docs/architecture.md) (how Drift works under the hood)\n\n**Verified live** on Windows 11 (Node v24.18.0, 2026-08-06): fresh clone →\nfirst `drift blame`\n\nin ~8.1 s, 10/10 checks pass, no registry 404 — and the\nnpm path (packed `@drift/*`\n\nchain installed into an empty dir) answers the MCP\nhandshake with all six tools in ~1 s. See the\n[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).\n\nIt starts the moment you run `drift init`\n\n. Drift creates `.drift/`\n\n— a SQLite DAG,\na config, and a per-repo Ed25519 keypair — and from then on every commit becomes\nan intent.\n\nWhen you (or your agent) run `drift realize -p \"<prompt>\"`\n\n, Drift *doesn't* just\ncommit. It parses the change semantically, **rejects the commit if the syntax is\nbroken** (exit 2 — broken code never enters history), redacts secrets from your\nprompt, computes an AST delta (ADDED / MODIFIED / DELETED / MOVED / RENAMED),\nsigns the intent, and stores it content-addressed in `.drift/objects/`\n\nbefore\ncommitting with a `Drift-Intent:`\n\ntrailer.\n\nAfter that, `drift blame`\n\ncan walk any line or function back to the prompt that\ncreated it, `drift context`\n\nhydrates the last intents for a file so an agent\ngrounds itself before editing, and `drift verify`\n\nre-runs the recorded\nverification command. A crashed agent runs `drift replay --checkout`\n\nand resumes\nexactly where it left off.\n\nAnd because these are MCP tools, your coding agent can use them directly —\n`drift_realize`\n\ninstead of `git commit`\n\n.\n\nDeeper reading: the full command reference lives in\n[docs/api.md](/lilcipherx/drift/blob/main/docs/api.md) (CLI flags, exit codes, JSON schemas, MCP tool\ninputs), and [docs/architecture.md](/lilcipherx/drift/blob/main/docs/architecture.md) explains the\nstorage model, encryption at rest, the webhook app, and the security\nboundaries.\n\nInstallation differs by harness. If you use more than one, install Drift\nseparately for each one. All harnesses expose the same six tools:\n`drift_realize`\n\n, `drift_context`\n\n, `drift_replay`\n\n, `drift_blame`\n\n, `drift_verify`\n\n,\n`drift_log`\n\n.\n\nStatus: theEvery section below leads with the`@drift/*`\n\nnpm packages are not published yet.clone path— it works right now from a checkout of this repository. The`npx -y @drift/mcp`\n\n/`npx -y @drift/cli`\n\none-liners activate automatically once the packages land on npm; until then they return a 404, so use the clone command shown first.\n\nEvery command below is backed by a real manifest in this repository\n(`.claude-plugin/plugin.json`\n\n, `.plugin/plugin.json`\n\n,\n`.cursor-plugin/plugin.json`\n\n, `.codex-plugin/plugin.json`\n\n,\n`gemini-extension.json`\n\n, `plugin.json`\n\n, `.factory-plugin/`\n\n,\n`package.json`\n\n→ `pi`\n\n) or a ready-made config in\n`examples/harness-configs/`\n\n. Today, installation needs **Node.js ≥ 24,\nnpm and a clone of this repository** (the MCP server runs straight from\n`packages/drift-mcp/dist/index.js`\n\n; no build step needed). Once the\n`@drift/*`\n\npackages are published, the same configs work via\n`npx -y @drift/mcp`\n\nwith no clone.\n\nInstall as a plugin from the Drift marketplace (plugin-style, like Superpowers):\n\n```\n/plugin marketplace add lilcipherx/drift\n/plugin install drift@drift\n```\n\nOr add the Drift MCP server directly (project scope) — from a clone:\n\n```\nclaude mcp add drift --env DRIFT_REPO=/abs/path/to/your/repo -- node /path/to/drift/packages/drift-mcp/dist/index.js\n```\n\nOnce the packages are published, the same command works via npx (no clone):\n\n```\nclaude mcp add drift --env DRIFT_REPO=/abs/path/to/your/repo -- npx -y @drift/mcp\n```\n\nOr copy the ready-made config:\n\n```\ncp examples/harness-configs/claude-code/.mcp.json .mcp.json\n```\n\nVerify with `claude mcp list`\n\n— you should see `drift`\n\nwith its six tools.\n\nThe marketplace manifest lives at\n\n`.claude-plugin/marketplace.json`\n\nin this repository (github-source`lilcipherx/drift`\n\n, strict plugin →`.claude-plugin/plugin.json`\n\nin the same repo).\n\nInstall Drift as a plugin from this repository:\n\n```\nagy plugin install https://github.com/lilcipherx/drift\n```\n\nAntigravity runs the plugin's session-start hook, so Drift is active from the first message. Reinstall with the same command to update.\n\nIn the Codex app, open **Settings → MCP servers** and add:\n\n**Name**:`drift`\n\n**Command**:`node`\n\n(clone path) — or`npx`\n\nonce the packages are published**Args**:`/path/to/drift/packages/drift-mcp/dist/index.js`\n\n— or`-y @drift/mcp`\n\nafter publication**Env**:`DRIFT_REPO=/abs/path/to/your/repo`\n\nAdd the Drift MCP server to `~/.codex/config.toml`\n\n(from a clone):\n\n```\n[mcp_servers.drift]\ncommand = \"node\"\nargs = [\"/path/to/drift/packages/drift-mcp/dist/index.js\"]\nenv = { DRIFT_REPO = \"/abs/path/to/your/repo\" }\n```\n\nOnce published, the same server runs via npx (no clone):\n\n```\n[mcp_servers.drift]\ncommand = \"npx\"\nargs = [\"-y\", \"@drift/mcp\"]\nenv = { DRIFT_REPO = \"/abs/path/to/your/repo\" }\n```\n\nRestart Codex, then ask for `drift_blame`\n\n/ `drift_context`\n\nin any session.\n\nCopy the ready-made config and enable MCP servers in Cursor settings:\n\n```\ncp examples/harness-configs/cursor/mcp.json .cursor/mcp.json\n```\n\nThen ask for `drift_blame`\n\nin chat.\n\n-\nRegister the marketplace:\n\n```\ndroid plugin marketplace add https://github.com/lilcipherx/drift\n```\n\n-\nInstall the plugin:\n\n```\ndroid plugin install drift@drift\n```\n\n-\nInstall the extension:\n\n```\ngemini extensions install https://github.com/lilcipherx/drift\n```\n\n-\nUpdate later:\n\n```\ngemini extensions update drift\n```\n\nAdd the Drift MCP server (from a clone):\n\n```\ncopilot mcp add drift -e DRIFT_REPO=/abs/path/to/your/repo -- node /path/to/drift/packages/drift-mcp/dist/index.js\n```\n\nOnce the packages are published, the same command works via npx (no clone):\n\n```\ncopilot mcp add drift -e DRIFT_REPO=/abs/path/to/your/repo -- npx -y @drift/mcp\n```\n\nOr copy the ready-made config to `.github/mcp.json`\n\nand restart Copilot.\n\nDrift is available in Kimi Code's plugin marketplace.\n\n-\nOpen Kimi Code's plugin manager:\n\n```\n/plugins\n```\n\n-\nGo to\n\n`Marketplace`\n\n>`Drift`\n\nand install it. -\nOr install directly from this repository:\n\n```\n/plugins install https://github.com/lilcipherx/drift\n```\n\n-\nDetailed docs:\n\n[docs/README.kimi.md](/lilcipherx/drift/blob/main/docs/README.kimi.md)\n\nOpenCode uses its own plugin install; install Drift separately even if you already use it in another harness.\n\n-\nTell OpenCode:\n\n```\nFetch and follow instructions from https://raw.githubusercontent.com/lilcipherx/drift/main/.opencode/INSTALL.md\n```\n\n-\nDetailed docs:\n\n[docs/README.opencode.md](/lilcipherx/drift/blob/main/docs/README.opencode.md)\n\nInstall Drift as a Pi package from this repository:\n\n```\npi install git:github.com/lilcipherx/drift\n```\n\nFor local development, run Pi with this checkout loaded as a temporary package:\n\n```\npi -e /path/to/drift\n```\n\nAdd the Drift MCP server to `.vscode/mcp.json`\n\n(native VS Code MCP support):\n\n```\ncp examples/harness-configs/claude-code/.mcp.json .vscode/mcp.json\n```\n\nVS Code picks it up on window reload.\n\nFrom a clone (works today):\n\n```\ngit clone https://github.com/lilcipherx/drift.git && cd drift\nnpm install\nnode packages/drift-cli/dist/cli.js --help\n```\n\nOnce the CLI is published to npm, `npx`\n\nworks without cloning:\n\n```\nnpx -y @drift/cli --help\n```\n\nOn your own repository:\n\n```\nnode /path/to/drift/packages/drift-cli/dist/cli.js init\n# … edit a file …\nnode /path/to/drift/packages/drift-cli/dist/cli.js realize -p \"Fix race condition in token refresh\" --agent --model claude-3-5-sonnet\nnode /path/to/drift/packages/drift-cli/dist/cli.js log\n```\n\nInstall `@drift/app`\n\nto get intent summaries on every pull request:\n\n- Reads\n`Drift-Intent:`\n\ntrailers from PR commits, hydrates the intent objects from`.drift/objects/`\n\nat 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:\n`drift-app start`\n\n(see`packages/drift-app/app.yml`\n\nfor the app manifest,`scripts/webhook-proxy.sh`\n\nfor local debugging).\n\nCheck intent health in CI:\n\n```\n- uses: lilcipherx/drift@v0.3.0\n  with:\n    command: log     # or: doctor / verify <intent-id>\n```\n\nThe 5-minute \"aha\" — a real Drift history, generated by the CLI itself:\n\n```\nbash scripts/seed-demo.sh\ncd examples/demo-repo\n\nnode ../../packages/drift-cli/dist/cli.js log\nnode ../../packages/drift-cli/dist/cli.js blame src/auth.ts --function refreshToken\n```\n\n`blame`\n\nprints the prompt, model and a **valid signature** for the function:\n\n```\nsrc/auth.ts:12 (refreshToken)\n  AGENT @ Drift Demo\n  model:   claude-3-5-sonnet\n  prompt:  Fix race condition in token refresh by de-duplicating in-flight refreshes\n  intent:  did_2941b4547b4ed505a7c37190247768a7\n  commit:  087c492f…  signature: valid\n```\n\n-\n**init**— Creates`.drift/`\n\n(SQLite DAG, config, Ed25519 keypair). Never rewrites history; deleting`.drift/`\n\nleaves a fully functional git repo. -\n**realize**— Commit with intent. Syntax gate (exit 2), secret redaction, AST delta, Ed25519 signature,`Drift-Intent:`\n\ntrailer. This is`git commit`\n\nfor the AI era. -\n**log**— Timeline of intents: id, author (agent vs human), model, prompt. -\n**blame / context**—`blame --line|--function`\n\nwalks a symbol back to its originating prompt;`context <file>`\n\nhydrates the last N intents for grounding. -\n**verify**— Re-runs the recorded verification command for an intent and checks the Ed25519 signature against the object file (never against DB rows). -\n**replay**— Restore a checkpointed agent state;`--checkout`\n\nresets the worktree. Crash recovery for agents. -\n**doctor**— DAG integrity, signature checks, orphan cleanup, encryption-key check when encryption is enabled.\n\n**The agent checks the intent before any task.** Mandatory for anyone touching\ngenerated code.\n\n| Package | What it does |\n|---|---|\n`@drift/cli` |\nThe `drift` CLI — `init` , `realize` , `log` , `blame` , `context` , `verify` , `replay` , `doctor` , `export` |\n`@drift/core` |\nIntent store (SQLite DAG), git wrapper, Ed25519 signatures, secret redaction, AES-256-GCM encryption at rest |\n`@drift/ast` |\nSemantic parser (TypeScript/JavaScript, Python) + AST deltas with a real syntax gate |\n\n| Package | What it does |\n|---|---|\n`@drift/mcp` |\nMCP server — six tools for Claude Code / Codex / Cline, delegates to the CLI |\n`@drift/sdk` |\nTyped SDK + Zod intent schemas |\n`@drift/app` |\nGitHub App — `pull_request` webhook that posts idempotent intent-summary comments |\n\n| Package | What it does |\n|---|---|\n`@drift/action` |\nGitHub Action (composite) — `log` / `doctor` / `verify` in CI |\n\n**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.\n\n- Every intent is\n**Ed25519-signed**; verification uses the object-file canonical JSON, so signature checks never need the master key. - Prompts are\n**regex-redacted** for secrets (AWS, OpenAI, GitHub, Slack, JWT, PEM, …) before any storage. **Encryption at rest (v0.2.0):**`[encryption] enabled = true`\n\n+`DRIFT_MASTER_KEY`\n\nencrypts`prompt`\n\nand`agentState`\n\nwith 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 (\n`.drift/keys/`\n\nis gitignored) except throwaway demo keys.\n\nThe [eval harness](/lilcipherx/drift/blob/main/eval/harness.mjs) (PRD §22) drives the real CLI with mock\nfile states — no LLM calls, no network — and records a baseline:\n\n```\nnpm run eval           # run scenarios + compare against baseline (regression gate)\nnpm run eval:record    # re-record eval/baseline.json\n```\n\nMetrics gated at >5% regression (PRD §22.3): **syntax-error rejection rate**\n(must be 100%), **blame accuracy**, **replay fidelity**. Scenarios live in\n[eval/scenarios/](/lilcipherx/drift/blob/main/eval/scenarios).\n\nSee [CONTRIBUTING.md](/lilcipherx/drift/blob/main/CONTRIBUTING.md). The general flow:\n\n- Fork the repository.\n- Create a branch for your work.\n- Keep\n`npm test`\n\ngreen (110 tests: unit, temp-git-repo integration, MCP JSON-RPC e2e, GitHub App handler + live webhook-server E2E + client-abort- graceful-shutdown robustness).\n\n- Keep the eval baseline green:\n`npm run eval`\n\n(PRD §22). - Submit a PR using the template.\n\nDesign decisions are tracked in [docs/adrs.md](/lilcipherx/drift/blob/main/docs/adrs.md) — note that the PRD\noriginally chose Rust (ADR-003); this implementation ships TypeScript-first\n(ADR-006) for a zero-native-dependency MVS. The `drift-ast`\n\nparser interface is\nthe drop-in point for a future tree-sitter implementation.\n\nOnce published, MCP servers launched via `npx -y @drift/mcp`\n\npick up new\nversions automatically (`npx`\n\nalways fetches the latest published release).\nUntil then, servers launched from a clone (the commands shown in\n[Installation](#installation)) track this checkout — update with\n\n```\ngit pull origin main\nnpm install\n```\n\nReleases are tagged on the\n[releases page](https://github.com/lilcipherx/drift/releases) (`v0.1.0`\n\n,\n`v0.2.0`\n\n, `v0.2.1`\n\n, …).\n\nChangelog: [CHANGELOG.md](/lilcipherx/drift/blob/main/CHANGELOG.md).\n\nMIT — see [LICENSE](/lilcipherx/drift/blob/main/LICENSE). Security notes: [SECURITY.md](/lilcipherx/drift/blob/main/SECURITY.md).\n\n**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`\n\n**Code of Conduct**:[CODE_OF_CONDUCT.md](/lilcipherx/drift/blob/main/CODE_OF_CONDUCT.md)", "url": "https://wpnews.pro/news/drift-intent-driven-versioning-for-ai-coding-agents", "canonical_source": "https://github.com/lilcipherx/drift", "published_at": "2026-08-12 19:32:41+00:00", "updated_at": "2026-08-12 19:40:37.482681+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools", "ai-infrastructure"], "entities": ["Drift", "Git", "Claude Code", "Cursor", "GitHub Copilot CLI", "Windows 11", "Node v24.18.0"], "alternates": {"html": "https://wpnews.pro/news/drift-intent-driven-versioning-for-ai-coding-agents", "markdown": "https://wpnews.pro/news/drift-intent-driven-versioning-for-ai-coding-agents.md", "text": "https://wpnews.pro/news/drift-intent-driven-versioning-for-ai-coding-agents.txt", "jsonld": "https://wpnews.pro/news/drift-intent-driven-versioning-for-ai-coding-agents.jsonld"}}