Skip to main content
Glama
AbstractGlitch

glitch-toolkit

by AbstractGlitch
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

glitch

A check that has stopped refusing things still passes. That is the failure this looks for.

On 8 September 2026, in the repository this package was extracted from, a test guarded the one chapter of a paid book that is given away free — asserting the sample stops at its cut and does not leak the rest. It was green. It was searching a page that had no book on it, for passages it therefore could never find, and passing. Nothing was broken; the redaction worked fine. The alarm had been disconnected and was still showing a green light.

Every guardrail decays that way eventually, and the decay is silent, because a guardrail that has stopped refusing looks exactly like one with nothing to refuse.

glitch installs six guardrails into your repository and then, whenever you ask, runs each one against a case it is supposed to refuse. One that no longer refuses anything fails here, loudly, instead of passing quietly.

pip install glitch-toolkit

glitch install     # put the artifacts in this repository
glitch status      # what is installed, what is not
glitch check --all # verify every step

No dependencies, no network calls, no telemetry. It writes nothing outside the directory you point it at.

What it actually checks

A step is not complete because a file is present. Every check does three things and reports which of them failed:

  1. finds the artifact

  2. runs it, and expects it to work

  3. runs it against a deliberately broken case, and expects it to refuse

Without the third, a check passes the moment you copy a file in, whether or not that file has any teeth left, and it would be green for every reader forever. tests/test_cli.py exists to prove the checker fails that case; its SABOTAGE test installs artifacts that run, exit 0 and refuse nothing.

Related MCP server: SDLC Command Center MCP Server

What install will not do

It will not write your CLAUDE.md, FLEET.md, FLOOR.md or PLAN.md. Four of the six steps are checked against your own file, because for those four the file is the work: a rules file that holds, a desk table with one committer, a floor measured twice, a plan someone else approved. A command that wrote them would turn the path into "you ran an installer". The FLOOR.md and PLAN.md templates ship deliberately unpassable for the same reason.

It will not overwrite. An artifact already in your repo is left alone and reported as kept; --force is how you say otherwise.

It writes nothing outside the directory you point it at, makes no network calls, and has no dependencies outside the standard library.

Running it without installing it

cli.py is one file and stays one file. Copy it into a repository and status and check work with nothing on the path and no install step — that property is deliberate and there is a test for the search paths it uses. Only install needs the rest of the package, and it says so plainly rather than failing oddly.

The MCP server (read-only)

uvx --from 'glitch-toolkit[mcp]' glitch-mcp --repo .

Install the extra in an isolated environment, not a system Python. The checker has no dependencies and that is a promise. The [mcp] extra is the opposite: mcp>=2.0 pulls pydantic, starlette, cryptography, opentelemetry and a dozen more, and pip will happily UPGRADE what is already there to satisfy them. Done against a global interpreter on 8 September 2026 it replaced pydantic 1.10 with 2.13 and starlette 0.46 with 1.6, breaking an unrelated FastAPI application on the same machine. uvx builds a throwaway environment and touches nothing else, which is why the registry entry launches it that way.

A virtualenv is equally fine:

python -m venv .venv && .venv/bin/pip install 'glitch-toolkit[mcp]'

It offers the checks to an agent as three tools — glitch_status, glitch_check, glitch_ledger_tail — and appends every question and answer to .claude/toolkit/ledger/ledger.jsonl.

It gates nothing. It cannot pause, block, refuse or intercept any action. It has no database connection, no credential and no network call. That is the whole first version, on purpose: a server that stands between an agent and a production database is serious software, and the honest order is to run read-only first, read the ledger, and find out what it would have refused before giving it the power to refuse. A gate built before that record exists is a guess with permissions.

The checks write nothing into your repository. The server breaks that in exactly one place — it appends to the ledger — and --no-ledger turns off even that, at the cost of the only thing worth keeping.

In Claude Code, .mcp.json:

{
  "mcpServers": {
    "glitch": { "command": "glitch-mcp", "args": ["--repo", "."] }
  }
}

The ledger

Append-only JSONL. Nothing rewrites a line it did not just write; a record that is overtaken is superseded by a new one and both stay; a field nobody measured is null rather than 0; a half-written last line is skipped and counted, never repaired, because repairing it means rewriting the file.

Tests

python tests/run_all.py      # all three suites, 40 tests

The server suite skips cleanly without the [mcp] extra and the runner reports that as SKIPPED rather than passing, because a green line meaning "we did not look" is the exact failure the gate-check practice exists to catch.

Where the checks come from

Every check here exists because something went wrong, and CORPUS.md is the list — what happened, what it cost, and which check catches it now.

It also names the ones nothing here catches yet, including the two that cost this package a version number each. A corpus that recorded only its solved failures would be doing the thing this package is about.

Licence

Apache License 2.0 — see LICENSE and NOTICE. Chosen over MIT for the patent grant.

Everything in this repository is under it. Use it commercially, change it, redistribute it.

The links above are absolute on purpose: this README is also the package's description on PyPI, where a relative link resolves against pypi.org and returns a 404.

Where this comes from

This repository is a published mirror. The package is developed inside a private monorepo alongside the book Building Your Store Or Your SaaS With Claude, whose practices it installs and checks, and it is pushed here as a subtree. The book, the shop that sells it and the rest of that repository are not open source and are not here. Nothing is being withheld from this repository that belongs to the package.

Issues and pull requests belong here rather than there, because here is the part anyone can read.

Status

Version 0.1.1. It installs, and the practices it checks are the six the book argues for. 0.1.0 was the first release; 0.1.1 changes this description and adds continuous integration, and nothing about what the code does.

What it is not yet: it gates nothing. glitch-mcp reports and records and cannot block an agent from doing anything. That is deliberate and the reasoning is in mcp_server.py — a server that stands between an agent and a production database should earn its evidence before it earns the power to refuse.

Available Tools

3 tools
glitch_checkVerify a practiceA
Read-only

Run one step's check, or all of them. A step passes only when its artifact is present, runs, AND still refuses a deliberately broken case. Returns a receipt per passing step. Reads only.

ParametersJSON Schema
NameRequiredDescriptionDefault
stepNoone of: rules, lanes, fleet, gates, floor, plan

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explicitly states 'Reads only', which aligns with the readOnlyHint annotation. It also explains the passing condition and that receipts are returned per passing step, adding behavioral detail beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, with three short sentences that convey the action, the condition for passing, and the return type. It is front-loaded with the primary purpose and contains no extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description gives enough context to understand the tool's behavior, including the return format (receipts per passing step) and the passing criteria. However, it does not detail the receipt structure or edge cases, but the simplicity of the tool mitigates this gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema fully documents the single parameter 'step' with an enum list and description. The tool description does not add additional meaning about the parameter, so it relies on the schema, which is comprehensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool runs checks for a step or all steps, with a specific passing condition and a return of receipts. It is specific enough to understand the core functionality, though the term 'check' is not elaborated on.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the sibling tools glitch_status or glitch_ledger_tail. There is no mention of alternatives or conditions for selection, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

glitch_ledger_tailRead the recordA
Read-only

The most recent entries from this repository's append-only ledger: what was asked of this server and what it answered. Supersession is reported, never applied, so a superseded entry is still visible.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds that entries are append-only and superseded entries remain visible, which is valuable beyond annotations. It clarifies the read-only nature and the treatment of supersession.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no fluff. The core purpose is front-loaded, and the behavior detail is provided efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one optional parameter and no output schema, the description covers the essential behavior (tail of ledger, supersession handling). It doesn't mention pagination or how to retrieve older entries, but that's not critical for this simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% as the description does not mention the limit parameter. The schema itself documents it well (default, min, max), but given low coverage, the description should compensate, and it fails to add any meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it reads the most recent entries from an append-only ledger, specifying the resource and the type of content (requests and responses). It distinguishes itself from siblings by focusing on the ledger tail, though it doesn't name alternatives explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the behavior (supersession reported, not applied) but does not provide explicit guidance on when to use this tool versus glitch_status or glitch_check. It implies it's for reading history but lacks clear alternative selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

glitch_statusRepository statusA
Read-only

Which of the six bounded-autonomy practices are installed in this repository and which are not. Reads only. A step reported as failing usually means the reader has not yet written their own file for it (CLAUDE.md, FLEET.md, FLOOR.md, PLAN.md), which is work, not a bug.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotation 'readOnlyHint: true', the description explicitly says 'Reads only' and explains the meaning of a failing step (not yet written file, not a bug). This adds valuable context about expected behavior and error interpretation, going beyond the annotation's simple flag.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is succinct, consisting of two clear sentences. The main purpose is front-loaded, and the additional clarification about failing steps is concisely appended. No unnecessary words or digressions are present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of an output schema, the description adequately explains what the tool reports (which practices are installed and which are not) and interprets the meaning of a failing step. This is sufficient for an agent to understand the tool's functionality without further schema details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so there is nothing to explain. The schema is empty and coverage is trivially 100%. The description adds no parameter-related confusion, and the empty parameter list is self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool checks which of the six bounded-autonomy practices are installed in the repository. It uses a specific verb ('are installed') and defines the resource (repository) and scope (the six practices), making the purpose unambiguous even without mentioning sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides interpretive guidance ('a step reported as failing usually means the reader has not yet written their own file'), but does not explicitly state when to choose this tool over the sibling tools (glitch_check, glitch_ledger_tail). It implies usage for status checks but lacks direct comparison or alternative selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.3
    • First observedglitch_check
    • First observedglitch_ledger_tail
    • First observedglitch_status
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct role: glitch_status reports installation state, glitch_check runs validation checks, and glitch_ledger_tail reviews audit history. There is no meaningful overlap between the three tools.

Naming Consistency5/5

All tool names share a consistent glitch_ prefix and snake_case noun style, making the naming predictable and uniform. Minor differences in compound length do not create confusion.

Tool Count5/5

Three tools is well-scoped for a narrow read-only inspection server. Each tool earns its place by covering a distinct aspect of the same workflow without redundancy.

Completeness5/5

The toolkit covers the core needs of the domain: checking what is installed, validating whether checks pass, and reading the audit ledger. Since the server is explicitly read-only, absent write or apply tools are not gaps.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • repo-health

    chenyinrusi
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides read-only repository health scanning tools for drift detection, module reachability, prompt bloat, evidence calibration, and registration completeness, enabling agents to diagnose repositories via MCP.
    2
    MIT

  • agenticrail-mcp

    MSMD-RUA
    F
    license
    Not graded
    quality
    C
    maintenance
    Provides tools to evaluate an AI agent's step before execution, returning signed ALLOW/DENY receipts, and to verify receipt chain integrity.
    -