{
  "markdown": "<!-- mcp-name: io.github.AbstractGlitch/glitch-toolkit -->\n<!-- The line above is how the official MCP registry proves this PyPI\n     package belongs to the namespace it claims. It is read out of the\n     project description, which is this file baked into the distribution\n     at build time, so it cannot be added to a release after the fact. -->\n\n# glitch\n\n**A check that has stopped refusing things still passes.** That is the failure\nthis looks for.\n\nOn 8 September 2026, in the repository this package was extracted from, a test\nguarded the one chapter of a paid book that is given away free — asserting the\nsample stops at its cut and does not leak the rest. It was green. It was\nsearching a page that had no book on it, for passages it therefore could never\nfind, and passing. Nothing was broken; the redaction worked fine. The alarm had\nbeen disconnected and was still showing a green light.\n\nEvery guardrail decays that way eventually, and the decay is silent, because a\nguardrail that has stopped refusing looks exactly like one with nothing to\nrefuse.\n\n`glitch` installs six guardrails into your repository and then, whenever you\nask, runs each one against a case it is *supposed* to refuse. One that no longer\nrefuses anything fails here, loudly, instead of passing quietly.\n\n```bash\npip install glitch-toolkit\n\nglitch install     # put the artifacts in this repository\nglitch status      # what is installed, what is not\nglitch check --all # verify every step\n```\n\nNo dependencies, no network calls, no telemetry. It writes nothing outside the\ndirectory you point it at.\n\n## What it actually checks\n\nA step is not complete because a file is present. Every check does three things\nand reports which of them failed:\n\n1. finds the artifact\n2. runs it, and expects it to work\n3. runs it against a deliberately broken case, and expects it to **refuse**\n\nWithout the third, a check passes the moment you copy a file in, whether or not\nthat file has any teeth left, and it would be green for every reader forever.\n`tests/test_cli.py` exists to prove the checker fails that case; its `SABOTAGE`\ntest installs artifacts that run, exit 0 and refuse nothing.\n\n## What `install` will not do\n\nIt will not write your `CLAUDE.md`, `FLEET.md`, `FLOOR.md` or `PLAN.md`. Four of\nthe six steps are checked against your own file, because for those four the file\n*is* the work: a rules file that holds, a desk table with one committer, a floor\nmeasured twice, a plan someone else approved. A command that wrote them would\nturn the path into \"you ran an installer\". The `FLOOR.md` and `PLAN.md` templates\nship deliberately unpassable for the same reason.\n\nIt will not overwrite. An artifact already in your repo is left alone and\nreported as kept; `--force` is how you say otherwise.\n\nIt writes nothing outside the directory you point it at, makes no network calls,\nand has no dependencies outside the standard library.\n\n## Running it without installing it\n\n`cli.py` is one file and stays one file. Copy it into a repository and `status`\nand `check` work with nothing on the path and no install step — that property is\ndeliberate and there is a test for the search paths it uses. Only `install`\nneeds the rest of the package, and it says so plainly rather than failing oddly.\n\n## The MCP server (read-only)\n\n```bash\nuvx --from 'glitch-toolkit[mcp]' glitch-mcp --repo .\n```\n\n**Install the extra in an isolated environment, not a system Python.** The\nchecker has no dependencies and that is a promise. The `[mcp]` extra is the\nopposite: `mcp>=2.0` pulls pydantic, starlette, cryptography, opentelemetry and\na dozen more, and pip will happily UPGRADE what is already there to satisfy\nthem. Done against a global interpreter on 8 September 2026 it replaced\npydantic 1.10 with 2.13 and starlette 0.46 with 1.6, breaking an unrelated\nFastAPI application on the same machine. `uvx` builds a throwaway environment\nand touches nothing else, which is why the registry entry launches it that way.\n\nA virtualenv is equally fine:\n\n```bash\npython -m venv .venv && .venv/bin/pip install 'glitch-toolkit[mcp]'\n```\n\nIt offers the checks to an agent as three tools — `glitch_status`, `glitch_check`,\n`glitch_ledger_tail` — and appends every question and answer to\n`.claude/toolkit/ledger/ledger.jsonl`.\n\n**It gates nothing.** It cannot pause, block, refuse or intercept any action. It\nhas no database connection, no credential and no network call. That is the whole\nfirst version, on purpose: a server that stands between an agent and a\nproduction database is serious software, and the honest order is to run\nread-only first, read the ledger, and find out what it *would* have refused\nbefore giving it the power to refuse. A gate built before that record exists is\na guess with permissions.\n\nThe checks write nothing into your repository. The server breaks that in exactly\none place — it appends to the ledger — and `--no-ledger` turns off even that, at\nthe cost of the only thing worth keeping.\n\nIn Claude Code, `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"glitch\": { \"command\": \"glitch-mcp\", \"args\": [\"--repo\", \".\"] }\n  }\n}\n```\n\n### The ledger\n\nAppend-only JSONL. Nothing rewrites a line it did not just write; a record that\nis overtaken is superseded by a new one and both stay; a field nobody measured\nis `null` rather than `0`; a half-written last line is skipped and counted, never\nrepaired, because repairing it means rewriting the file.\n\n## Tests\n\n```bash\npython tests/run_all.py      # all three suites, 40 tests\n```\n\nThe server suite skips cleanly without the `[mcp]` extra and the runner reports\nthat as SKIPPED rather than passing, because a green line meaning \"we did not\nlook\" is the exact failure the gate-check practice exists to catch.\n\n## Where the checks come from\n\nEvery check here exists because something went wrong, and\n[CORPUS.md](https://github.com/AbstractGlitch/glitch-toolkit/blob/main/CORPUS.md)\nis the list — what happened, what it cost, and which check catches it now.\n\nIt also names the ones nothing here catches yet, including the two that cost\nthis package a version number each. A corpus that recorded only its solved\nfailures would be doing the thing this package is about.\n\n## Licence\n\nApache License 2.0 — see [LICENSE](https://github.com/AbstractGlitch/glitch-toolkit/blob/main/LICENSE)\nand [NOTICE](https://github.com/AbstractGlitch/glitch-toolkit/blob/main/NOTICE). Chosen over MIT for\nthe patent grant.\n\nEverything in this repository is under it. Use it commercially, change it,\nredistribute it.\n\nThe links above are absolute on purpose: this README is also the package's\ndescription on PyPI, where a relative link resolves against `pypi.org` and\nreturns a 404.\n\n## Where this comes from\n\nThis repository is a published mirror. The package is developed inside a private\nmonorepo alongside the book *Building Your Store Or Your SaaS With Claude*, whose\npractices it installs and checks, and it is pushed here as a subtree. The book,\nthe shop that sells it and the rest of that repository are **not** open source\nand are not here. Nothing is being withheld from this repository that belongs to\nthe package.\n\nIssues and pull requests belong here rather than there, because here is the part\nanyone can read.\n\n## Status\n\nVersion 0.1.1. It installs, and the practices it checks are the six the book\nargues for. 0.1.0 was the first release; 0.1.1 changes this description and adds\ncontinuous integration, and nothing about what the code does.\n\nWhat it is not yet: it gates nothing. `glitch-mcp` reports and records and\ncannot block an agent from doing anything. That is deliberate and the reasoning\nis in `mcp_server.py` — a server that stands between an agent and a production\ndatabase should earn its evidence before it earns the power to refuse.\n",
  "bytes": 7759,
  "sha": "58efc37203fe39358e5082c2e31be7cbe16974d7af6a95f2628590ba578019fc",
  "repo_slug": "abstractglitch/glitch-toolkit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_abstractglitch_glitch_toolkit_b8491f64/readme"
}