<p align="center">
  <img src="docs/assets/drift-hero.png" width="420" alt="Drift — the robot that sees the why inside the code" />
</p>

<h1 align="center">Drift</h1>
<p align="center"><em>Git tracks what changed. Drift tracks why.</em></p>

Drift adds a **provenance layer to Git for AI-generated code**. Every commit
becomes an *Intent* — the prompt that produced the change, the model behind it,
and the verification that approved it — signed, stored, and traceable months
later.

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![Node](https://img.shields.io/badge/node-%3E%3D24-green)
[![Tests](https://img.shields.io/badge/tests-123%20passing-brightgreen)](tests/)
[![CI](https://img.shields.io/badge/CI-GitHub%20Actions-blue)](.github/workflows/ci.yml)

---

## The 30-second demo

```bash
git clone https://github.com/lilcipherx/drift.git && cd drift
npm install
bash scripts/seed-demo.sh && cd examples/demo-repo

node ../../packages/drift-cli/dist/cli.js blame src/auth.ts --function refreshToken
```

Real output:

```
src/auth.ts:16 (refreshToken)

  Why:
    Fix race condition in token refresh by de-duplicating in-flight refreshes

  Generated by:
    AGENT @ Drift Demo (model: claude-3-5-sonnet)

  Intent:
    did_910ac75de855a684937f8cc016976442

  Commit:
    fa20f02884a910f26e3f869ceaf6b89fa7e8207f  signature: valid
```

Months from now, that function answers *why it exists, who (or what) created
it, and that the claim is cryptographically signed.*

---

## Install

Two ways to get the CLI + MCP server:

**From a checkout (works today):**

```bash
git clone https://github.com/lilcipherx/drift.git && cd drift
npm install
node packages/drift-cli/dist/cli.js --help
```

**From npm (once the `@drift/*` packages are published):**

```bash
npx -y @drift/cli --help            # CLI
npx -y @drift/mcp                   # MCP server for agents
```

Per-harness install for **11 agents** (Claude Code, Antigravity, Codex App/CLI,
Cursor, Factory Droid, Gemini CLI, GitHub Copilot CLI, Kimi Code, OpenCode,
Pi, VS Code): see **[docs/installation.md](docs/installation.md)**. The
[GitHub Action](docs/installation.md#github-action-ci-check--pr-comment) runs
`drift log`/`doctor`/`verify` in CI and posts the PR summary comment.

---

## 60-second quickstart

```bash
cd /path/to/your/repo
node /abs/path/to/drift/packages/drift-cli/dist/cli.js init     # 1. create .drift/
# … edit a file …
node /abs/path/to/drift/packages/drift-cli/dist/cli.js realize -p "Add login flow with validation" --agent --model claude-3-5-sonnet
node /abs/path/to/drift/packages/drift-cli/dist/cli.js status    # 2. what's recorded?
node /abs/path/to/drift/packages/drift-cli/dist/cli.js blame src/auth.ts --function login   # 3. why does this exist?
```

`realize` is `git commit` for the AI era: it **rejects broken syntax before it
enters history** (exit 2), redacts secrets from your prompt, computes an AST
delta, signs the intent, and commits with a `Drift-Intent:` trailer. The full
[5-minute quickstart](docs/quickstart.md) has the measured end-to-end walk.

---

## On GitHub — the PR summary

When Drift is used in a repository, every pull request gets a compact
provenance summary (posted by the GitHub App or the Action, updated in place —
never spammed):

> ## 🤖 Drift intent summary
>
> 1 intent on this PR · 1 author
>
> ### Intent `did_910a…`
>
> **Author:** `claude-code` (AGENT) · **Model:** `claude-3-5-sonnet` · **Signature:** ✍ Ed25519
>
> > Add retry handling to the payment webhook with exponential backoff and a dead-letter queue for permanent failures.
>
> | File | Change |
> | --- | --- |
> | `src/webhooks/payment.ts` | **MODIFIED** — add retryWebhook() with backoff |
> | `src/webhooks/signature.ts` | **MODIFIED** — verify signature before enqueue |
> | `src/webhooks/process.ts` | **ADDED** — add processPaymentEvent() handler |

Review the intent, not 2,000 lines of diff.

---

## Why Drift?

Git tells you *what* changed — a text diff. As more code is generated by AI,
reviewing thousands of lines of diff tells you nothing about *why* they exist,
*what* the model was asked to do, or *how* the change was verified.

Drift records exactly that, at commit time:

- **Intent** — the prompt: what was asked and why.
- **Provenance** — who (human) or what (agent + model) produced it.
- **Verification** — the recorded command that approved it (`drift verify`).
- **Signature** — Ed25519-signed and content-addressed, so the record is
  tamper-evident (`drift verify-intent`).
- **Recovery** — a crashed agent resumes from its last checkpoint
  (`drift replay --checkout`).

---

## How it works

1. **`drift init`** creates `.drift/` — a SQLite intent store, a config, and a
   per-repo Ed25519 key. Git history is never rewritten.
2. **`drift realize`** stages, syntax-checks, redacts, AST-diffs, signs, stores
   the intent in `.drift/objects/`, and commits with a `Drift-Intent:` trailer.
3. **`drift blame` / `drift context`** map any line or function back to the
   intent that created it.
4. **`drift verify`** re-runs the recorded verification command.
5. **`drift doctor`** checks store integrity and repairs orphans (`--fix`).

Deeper: [docs/architecture.md](docs/architecture.md) (storage, crypto, the
GitHub App) and [docs/api.md](docs/api.md) (every command, flag, exit code and
MCP tool).

---

## Security & privacy

- **Prompts never leak into git history by default.** `[prompts] mode` in
  `.drift/config.toml`: `commit-summary` (default — full prompt only in the
  local, gitignored `.drift/` store; the commit carries a safe `Intent:` /
  `Model:` / `Verification:` summary), `full` (opt-in, legacy), `none`
  (prompt stored nowhere).
- **Secrets are redacted** (AWS, OpenAI, GitHub, Slack, JWT, PEM, …) before
  any storage.
- **Encryption at rest** (optional): `[encryption] enabled = true` +
  `DRIFT_MASTER_KEY` → AES-256-GCM for prompts and agent state.
- **No telemetry, no network** — the CLI works fully offline.
- Full threat model: [SECURITY.md](SECURITY.md).

---

## Contributing

Contributors welcome — see [CONTRIBUTING.md](CONTRIBUTING.md), the
[good-first-issue list](docs/GOOD_FIRST_ISSUES.md), and our
[Code of Conduct](CODE_OF_CONDUCT.md). Design decisions are tracked in
[docs/adrs.md](docs/adrs.md).

**Documentation:** [quickstart](docs/quickstart.md) · [installation](docs/installation.md) · [API reference](docs/api.md) · [architecture](docs/architecture.md) · [changelog](CHANGELOG.md)

**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; the packed
`@drift/*` chain answers the MCP handshake with all six tools in ~1 s — see
the [measured tables](docs/quickstart.md#verified-live-проверено-вживую).

## License

MIT — see [LICENSE](LICENSE). Security notes: [SECURITY.md](SECURITY.md).
Issues & releases: [github.com/lilcipherx/drift](https://github.com/lilcipherx/drift).