{
  "markdown": "# Litescope\n\n**Let AI agents touch production SQLite — safely.** Diagnose before the write, rewind after it. For Cloudflare D1, Turso, and local files.\n\n[Website](https://litescope-site.pages.dev) · [Roadmap](ROADMAP.md) · [Sponsor](https://github.com/sponsors/croc100)\n\n[![License: AGPL v3](https://img.shields.io/badge/license-AGPL%20v3-3fb6a8)](LICENSE)\n[![Go](https://img.shields.io/badge/go-1.26-00ADD8?logo=go&logoColor=white)](go.mod)\n[![Cloudflare D1](https://img.shields.io/badge/Cloudflare%20D1-native-f48120?logo=cloudflare&logoColor=white)](https://developers.cloudflare.com/d1/)\n[![Turso](https://img.shields.io/badge/Turso-supported-4ec9b0)](https://turso.tech)\n[![Contributors](https://gcv-five.vercel.app/api/badge/croc100/litescope)](https://gcv-five.vercel.app/croc100/litescope)\n[![Litescope MCP server](https://glama.ai/mcp/servers/croc100/Litescope/badges/score.svg)](https://glama.ai/mcp/servers/croc100/Litescope)\n\nAsk Claude to change your D1 database — and undo it if it's wrong. Every write is dry-run by default with the exact blast radius, and one call away from revert.\n\n![Litescope reversible-write loop: dry-run blast radius, apply with a rewind token, then one-call undo](docs/assets/reversible-write-demo.svg)\n\n**Free and open source (AGPL-3.0)** — every command, every fleet operation, self-hostable, no license key. The only paid thing is the [hosted dashboard we run for you](#pricing--whats-free).\n\n---\n\n## Why a tool for SQLite?\n\n\"It's just a file — what's there to operate?\"\n\nThat was true when SQLite was a local dev toy. It isn't anymore. D1, Turso,\nLiteFS, and Litestream put SQLite in **production at fleet scale** — thousands of\ndatabases, one per tenant. But the tooling never caught up:\n\n- **`sqlite3` assumes one database.** Production assumes thousands. There's no\n  `pg_stat`, no APM, no standard way to see *from the outside* why a database is\n  locked, why WAL is bloating, or which tenant went silent.\n- **Embedded means unobservable.** The very thing that makes SQLite great — no\n  server — is what leaves you blind in production.\n- **Agents now write to your data.** No SQLite tool was built assuming an AI\n  would run the migration. Litescope was.\n\nPostgres has a mature tool for every problem. SQLite has none — so Litescope is\n**one binary for the whole job**: fleet observability, file-level superpowers\n(bisect / rewind / salvage), lock & WAL diagnostics, and a safe interface for\nagents. Things a generic DB client structurally can't do.\n\n---\n\n## MCP — Give Claude direct access to your D1\n\n**Claude Code** — one line (read-only):\n\n```bash\nclaude mcp add litescope -- litescope mcp\n```\n\nWith writes + D1 (Litescope still dry-runs every write and captures a rewind\npoint before applying):\n\n```bash\nclaude mcp add litescope \\\n  -e CLOUDFLARE_API_TOKEN=your-token \\\n  -e CLOUDFLARE_ACCOUNT_ID=your-account-id \\\n  -- litescope mcp --allow-writes\n```\n\n**Cursor** — one-click:\n[**➕ Add litescope to Cursor**](cursor://anysphere.cursor-deeplink/mcp/install?name=litescope&config=eyJjb21tYW5kIjoibGl0ZXNjb3BlIiwiYXJncyI6WyJtY3AiXX0=)\n(installs read-only; add `--allow-writes` and the Cloudflare env vars in\n`mcp.json` to enable writes).\n\n**Claude Desktop / Windsurf / any MCP client** — add to the config file directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"litescope\": {\n      \"command\": \"litescope\",\n      \"args\": [\"mcp\", \"--allow-writes\"],\n      \"env\": {\n        \"CLOUDFLARE_API_TOKEN\": \"your-token\",\n        \"CLOUDFLARE_ACCOUNT_ID\": \"your-account-id\"\n      }\n    }\n  }\n}\n```\n\nAlso listed in the [MCP Registry](https://registry.modelcontextprotocol.io)\nas `io.github.croc100/litescope`.\n\nThen ask Claude things like:\n\n```\n\"List my D1 databases\"\n\"Show me the schema of the users table in d1://abc-123\"\n\"Delete every inactive user from d1://prod-db-id\"     ← dry-run first: shows the\n                                                        exact blast radius before\n                                                        you approve the write\n\"Undo that — put it back the way it was\"              ← one-call revert via the\n                                                        rewind_token from the write\n\"The deploy at 2pm broke something — rewind prod to 1:45pm\"\n\"Diff my local dev.db against d1://prod-db-id and show me the migration SQL\"\n```\n\n### Read-only tools (always available)\n\n| Tool | What it does |\n|---|---|\n| `litescope_d1_list` | List all D1 databases in the account (UUID, name, DSN) |\n| `litescope_query` | Run a SELECT on any D1 database or local SQLite file |\n| `litescope_schema` | Inspect tables, columns, indexes |\n| `litescope_health` | Check for corruption, WAL bloat, fragmentation |\n| `litescope_diff` | Schema and row-count diff between any two sources |\n| `litescope_migrate_plan` | Generate migration SQL + blast-radius analysis |\n| `litescope_migrate_diff` | Generate migration SQL only (no blast-radius) |\n| `litescope_advise` | Performance analysis: missing indexes, full table scans |\n| `litescope_check` | Verify a backup against a reference database |\n| `litescope_fingerprint` | Cluster a fleet by schema fingerprint |\n| `litescope_fleet_health` | Triage faults across a whole fleet |\n| `litescope_locks` | Diagnose `database is locked` / SQLITE_BUSY (static + live) |\n| `litescope_snapshot_list` | List point-in-time snapshots for a local database |\n\n`litescope_query` enforces **token budgeting** — `max_rows` cap + `columns`\nprojection + truncation reporting — so a large table never blows the agent's\ncontext window.\n\n### Write tools (`--allow-writes`)\n\n| Tool | What it does |\n|---|---|\n| `litescope_query_write` | Mutating SQL — **dry-run by default** with exact rows affected and blast-radius diff (D1 dry-runs measured on a pulled copy); on apply, captures an undo point first (local: snapshot, D1: Time Travel bookmark) and returns it as a `rewind_token` |\n| `litescope_write_undo` | Revert a write in one call using its `rewind_token` — local files and D1 alike; tokens are bound to the database they were minted for |\n| `litescope_migrate_apply` | Apply a migration — same reversible contract as `litescope_query_write` |\n| `litescope_autopilot` | Self-driving optimization (ANALYZE, indexes, VACUUM) — dry-run by default |\n| `litescope_snapshot` | Take a point-in-time backup of a local database |\n| `litescope_restore` | Restore a local database from a snapshot |\n| `litescope_rewind` | Restore a D1 database to a point in time (Time Travel) |\n| `litescope_d1_pull` | Download a D1 database to a local SQLite file |\n| `litescope_d1_create` | Create a new D1 database |\n| `litescope_d1_delete` | Delete a D1 database (irreversible) |\n\nWrite tools are off unless you start the server with `--allow-writes`, every\nwrite is dry-run by default, and no write commits without an auto-captured undo\npoint. See the [security model](SECURITY.md) for the full boundary — what each\nlayer protects against, and what it doesn't.\n\n### Prompts & Resources\n\nBeyond tools, the MCP server exposes **prompts** — canned workflows like\n`diagnose_locked_database`, `review_migration`, `safe_optimize`, and\n`health_checkup` that chain the tools above into a safe plan — and\n**resources**: a database's schema, data dictionary, live health, and live lock\ndiagnosis — readable by the agent without spending a tool call, and\nsubscribable for push updates whenever the underlying file changes. Bind one\nwith `litescope mcp ./app.db`, or address any source via\n`litescope://schema/{source}`, `litescope://dictionary/{source}`,\n`litescope://health/{source}`, and `litescope://locks/{source}`.\n\nThe server implements **MCP 2025-06-18**: tool annotations (read-only /\ndestructive hints), structured output (`structuredContent` + `outputSchema`),\nargument completion, resource-change subscriptions, and server logging.\n\n### Remote / hosted (Streamable HTTP)\n\nBy default `litescope mcp` speaks stdio. For a hosted, remote, or multi-client\nsetup, serve over the Streamable HTTP transport instead:\n\n```bash\nlitescope mcp --http :7577 --http-token \"$LITESCOPE_MCP_TOKEN\"\n```\n\nPOST a JSON-RPC message to the endpoint (`/mcp` by default), or open a `GET` SSE\nstream for server notifications; each client gets its own session via the\n`Mcp-Session-Id` header.\n\nBefore exposing it publicly, lock it down: `--http-token` (or the\n`LITESCOPE_MCP_TOKEN` env var) requires `Authorization: Bearer <token>` on every\nrequest, and `--http-origin` allowlists browser Origins (localhost is always\nallowed) for DNS-rebinding protection. Without a token the endpoint is open and\nthe server prints a warning.\n\n---\n\n## D1 — CLI operations\n\n### Rewind — D1 Time Travel\n\n```bash\n# Restore to a previous point in time\nlitescope rewind d1://DB_ID --to \"2h ago\"\nlitescope rewind d1://DB_ID --to \"yesterday\"\nlitescope rewind d1://DB_ID --to \"2024-01-15T10:30:00Z\"\n\n# List available restore points (30-day window + migration timestamps)\nlitescope rewind list d1://DB_ID\n```\n\n### Pull / Push — sync between D1 and local SQLite\n\n```bash\n# Download D1 → local (for inspection, backup, or diffing)\nlitescope d1 pull d1://DB_ID ./snapshot.db\n\n# Upload local → D1 (seed a fresh database or restore from snapshot)\nlitescope d1 push ./seed.db d1://DB_ID\nlitescope d1 push ./seed.db d1://DB_ID --drop-existing\n```\n\n### Migrate — schema changes on D1\n\n```bash\n# Diff local dev schema against live D1 — generate migration SQL\nlitescope migrate local.db d1://DB_ID\n\n# Apply a migration directly to D1\nlitescope migrate apply d1://DB_ID migration.sql\n```\n\n### Bisect — find which commit broke a D1 database\n\nBinary-search D1 Time Travel to pinpoint the exact snapshot where a query\nstarted returning wrong results:\n\n```bash\nlitescope bisect d1://DB_ID \\\n  --good \"3d ago\" \\\n  --bad now \\\n  --check \"SELECT COUNT(*) FROM orders WHERE status = 'paid'\" \\\n  --expect \"gt:0\"\n```\n\nChecks `gt:0` (greater-than), `lt:N`, `eq:N`, or a literal value. Narrows\nto the snapshot window where the condition first failed, then lets you\ninspect or rewind.\n\n---\n\n## Local SQLite\n\n### `doctor` — one-shot checkup\n\n```bash\nlitescope doctor app.db\nlitescope doctor app.db --deep            # exhaustive integrity_check\nlitescope doctor app.db --format html -o report.html\n```\n\nCombines integrity check, WAL/fragmentation health, index advisor, and schema lint in one command. Exits **1** when attention is needed — use it as a CI quality gate.\n\n### `snapshot` / `restore` — point-in-time backups\n\n```bash\nlitescope snapshot app.db                     # consistent VACUUM INTO copy\nlitescope snapshot app.db --label before-migration\nlitescope snapshot app.db --keep 7            # retain only the 7 newest\nlitescope snapshot list app.db\nlitescope restore app.db                      # restore the newest snapshot\nlitescope restore app.db --from <snapshot.db>\n```\n\nSnapshots live in a sibling `.litescope-snapshots/` directory. Restore is\nintegrity-checked and takes a pre-restore safety snapshot first — the same\n\"did you back up?\" safety net that D1 gets from Time Travel, for local and Turso.\n\n### `autopilot` — self-driving optimization\n\n```bash\nlitescope autopilot app.db                    # dry-run: show the plan\nlitescope autopilot app.db --apply            # apply the safe actions\nlitescope autopilot app.db --apply --aggressive\nlitescope autopilot --fleet litescope.fleet.yaml --apply\n```\n\nRuns `ANALYZE` + `PRAGMA optimize`, adds missing foreign-key indexes, and\n(with `--aggressive`) VACUUMs and drops redundant indexes — each explained in\nplain language. Dry-run by default; every real change is preceded by an\nautomatic snapshot.\n\n### `locks` — diagnose \"database is locked\"\n\n```bash\nlitescope locks app.db                        # static config diagnosis\nlitescope locks app.db --live                 # is a writer holding the lock now?\nlitescope locks app.db --watch                # stream lock-state changes\nlitescope locks app.db --timeline             # recorded contention history\nlitescope locks app.db --timeline --since 24h\n```\n\nInspects journal mode, `busy_timeout`, locking mode, and WAL bloat, and\nprescribes the exact PRAGMA/DSN fix. `--live` identifies the process holding\nthe lock right now. `--watch` records every observation to a local history\nstore; `--timeline` then aggregates it into a per-database contention view —\nwhen the database was jammed, for how long, which processes held it, wait-time\npercentiles, and whether the WAL checkpoint kept up.\n\n### `diff` — schema and data diff\n\n```bash\nlitescope diff old.db new.db\nlitescope diff old.db new.db --format json\nlitescope diff local.db d1://DB_ID        # local vs live D1\nlitescope diff local.db turso://TOKEN@ORG/prod\n```\n\n### `migrate` — generate and apply migrations\n\n```bash\nlitescope migrate before.db after.db --output migration.sql\nlitescope migrate apply prod.db migration.sql --dry-run\nlitescope migrate apply prod.db migration.sql --verify after.db\n```\n\n`migrate apply` safety sequence: pre-flight integrity check → `VACUUM INTO` backup → single transaction → FK verification → auto-rollback on failure.\n\n### `lint` — schema anti-patterns\n\n```bash\nlitescope lint app.db\nlitescope lint app.db --strict   # exit 1 on info findings too\n```\n\nRules: `no-primary-key`, `untyped-column`, `not-strict`, `autoincrement-overhead`, `non-integer-pk`.\n\n### `schema` — inspect schema + ERD\n\n```bash\nlitescope schema app.db\nlitescope schema app.db --erd    # Mermaid ER diagram\n```\n\n### `dump` — portable SQL export\n\n```bash\nlitescope dump app.db -o backup.sql\nlitescope dump app.db --schema-only\nlitescope dump app.db --table users\n```\n\n### `import` / `export` — spreadsheets and SQLite\n\n```bash\nlitescope import sales.csv              # → sales.db, table \"sales\"\nlitescope import budget.xlsx            # first sheet → budget.db\nlitescope export shop.db --table orders -o orders.xlsx\nlitescope export shop.db --query \"SELECT city, COUNT(*) FROM users GROUP BY city\"\n```\n\nFormats: CSV, TSV, JSON, Excel (`.xlsx`). No external dependencies.\n\n### `monitor` — schema drift detection\n\n```bash\nlitescope monitor snapshot prod.db --output baseline.json\nlitescope monitor check prod.db --baseline baseline.json     # exits 1 on drift\nlitescope monitor watch prod.db --baseline baseline.json --interval 1h --webhook https://hooks.slack.com/...\n```\n\n### `serve` — local web dashboard\n\n```bash\nlitescope serve                   # opens http://127.0.0.1:7575\nlitescope serve --config litescope.fleet.yaml\n```\n\nFleet topology map, health triage, schema fingerprinting, interactive ERD, a\npaginated data browser with a visual query builder, drag-drop import, and a\n**visual diff panel** — pick any two databases to review schema and row-count\nchanges before applying. Entirely local, no account required.\n\n---\n\n## Fleet\n\nManage hundreds of databases at once. Built for multi-tenant apps on Turso and D1.\n\n```bash\n# Discover all databases\nlitescope fleet discover turso --org my-org --token $TURSO_API_TOKEN\nlitescope fleet discover d1 --account $CF_ACCOUNT_ID --token $CF_API_TOKEN\n\n# Triage the whole fleet\nlitescope fleet health\nlitescope fleet locks         # roll up \"database is locked\" contention, worst-first\nlitescope fleet fingerprint   # cluster by schema — find drift before it bites\n\n# Stage a migration across the fleet\nlitescope fleet migrate migration.sql --dry-run\nlitescope fleet migrate migration.sql --canary 5\nlitescope fleet migrate migration.sql\n```\n\n---\n\n## CI — GitHub Action\n\nRun Litescope on every pull request — lint the schema, diff against the base\nbranch, and comment the blast radius so a risky migration can't merge unreviewed.\n\n```yaml\n- uses: croc100/Litescope@v1\n  with:\n    args: \"lint app.db --strict\"\n    comment: \"true\"          # post the result as a sticky PR comment\n```\n\n`args` is any Litescope command; the job exits non-zero when Litescope flags\nsomething, failing the check. See\n[examples/github-actions/migration-ci.yml](examples/github-actions/migration-ci.yml)\nfor a full lint + diff workflow.\n\n| Input | Default | Description |\n|---|---|---|\n| `args` | — | Litescope command to run (required) |\n| `version` | `latest` | Release tag to install, or `latest` |\n| `comment` | `false` | Post output as a sticky PR comment |\n| `working-directory` | `.` | Directory to run in |\n\n---\n\n## Install\n\n**Homebrew**\n\n```bash\nbrew install croc100/tap/litescope\n```\n\n**npm / npx** — for JS and `wrangler` users, no separate install:\n\n```bash\nnpx litescope doctor app.db\nnpm install -g litescope\n```\n\n**Go install**\n\n```bash\ngo install github.com/croc100/litescope/cmd/litescope@latest\n```\n\n**Binary download**\n\nmacOS, Linux, Windows — [Releases](https://github.com/croc100/Litescope/releases).\n\n---\n\n## Remote sources\n\n| DSN | Provider |\n|---|---|\n| `./app.db` or `/path/to/file.db` | Local SQLite file |\n| `d1://DB_UUID` | Cloudflare D1 (env: `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID`) |\n| `d1://TOKEN@ACCOUNT_ID/DB_UUID` | Cloudflare D1 (explicit credentials) |\n| `turso://TOKEN@ORG/DBNAME` | [Turso](https://turso.tech) |\n\n---\n\n## Pricing — what's free\n\nThe tool is free. We only charge to run the dashboard for you.\n\n| | **Free** (OSS, AGPL-3.0) | **Cloud** (paid) |\n|---|---|---|\n| Every CLI command, MCP server, fleet ops | ✅ | ✅ |\n| `litescope serve` — local web dashboard | ✅ | ✅ |\n| Self-hosted dashboard on your own infra | ✅ | ✅ |\n| **Hosted dashboard we run & maintain** | — | ✅ |\n| Managed metadata ingestion, retention, alerting | — | ✅ |\n| Org auth, teams, SSO | — | ✅ |\n| Support SLA | — | ✅ |\n\n**The line is simple: the software and every feature is free and self-hostable\nforever. You pay only if you want us to host and operate the dashboard so you\ndon't have to.** No feature is locked behind a license key.\n\nSee [litescope-site.pages.dev/pricing](https://litescope-site.pages.dev) for the\nhosted plans.\n\n---\n\n## License\n\nLitescope is **AGPL-3.0**. Free to use, modify, and self-host. If you offer it\nas a network service the AGPL requires you to share your modifications. A\ncommercial license (AGPL exception + support SLA) is available for\norganizations — see [COMMERCIAL.md](COMMERCIAL.md) or email\n**dl_litescope@crode.net**.\n",
  "bytes": 18068,
  "sha": "f7c40f0d8bf474dad1173b1280639677bf6a7698772a312ea04a43f14b98a9f8",
  "repo_slug": "croc100/litescope",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_croc100_litescope_be49b3bf/readme"
}