Skip to main content
Glama
dahshanlabs

klypix-mcp

by dahshanlabs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Project rules from the brain's lessons — enforced before CI, with no AI at check time

brain_rules

Converts recorded lessons into deterministic, versioned diff rules that check edits and commits before code reaches CI, warning by default and blocking only after human approval.

Instructions

Turns lessons this brain recorded ("every new route must also be in PRIVATE_ROUTES", "a new *.test.ts must be listed in package.json", "this file is mixed CRLF/LF") into DETERMINISTIC diff checks, versioned in the repo as .klypix/rules.json, each citing the card it came from. Checked before the code reaches CI: brain_sync shows the rules for the files you declare; the edit hook (Claude Code; Codex gets the same) and an opt-in git pre-commit/pre-push hook report findings. Rules WARN by default; only a rule the human approved with --block stops an edit (Claude Code) or a commit, and a commit that skips a blocking rule (--no-verify) is recorded. Actions: "propose" routes each lesson to rule / instruction / note and drafts the checkable ones; "add" writes completed drafts as CANDIDATES (inert); "promote" and "retire" without approve open a human review prompt (MCP form or Windows dialog); never answer it for the human or repeat after decline unless asked. Other hosts can use the human's 8-character approval code (npx klypix-mcp rules code promote|retire <ids> — never shown to you, never guess it; a rule that blocks you is lifted only by the human); "check" runs the rules on the working tree, the staged change, or a range (include_candidates:true tests candidates before approval); "status" lists rules with fires / blocks / overrides / false alarms and retirement suggestions; "false_alarm" records that a finding was wrong (it does not lift the rule). Kinds: listed-in, forbid-pattern, preserve-eol, cloud-required. Checks are string/glob/regex work over the diff — milliseconds, offline; the project's own tests stay with its CI.

Input Schema

NameRequiredDescriptionDefault
idsNopromote / retire / false_alarm: rule ids.
baseNocheck: base ref for a range (merge-base with head is used).
headNocheck: head ref for a range (default HEAD).
modeNocheck: the working tree vs HEAD (default), the staged change, or a commit range (with base).
blockNopromote: request blocking checks instead of warnings; the human reviews this severity in the approval prompt. With a terminal code, must match --block.
filesNocheck: just list the rules these files fall under (no diff).
limitNopropose: at most this many lessons (default 30).
queryNopropose: only lessons containing this text.
rulesNoadd: complete rules — {id, kind, severity, why, fix, source:{card}, files:[globs], …kind fields}. listed-in: when "added-files"|"added-lines", registry:[files], needle (template: {file} {basename} {name} {relpath} {1}), pattern for added-lines (capture group 1 = the value to find). forbid-pattern: pattern. preserve-eol: files only. cloud-required: files, severity "advise".
actionYesWhat to do. Default flow: propose → add → (human) promote; check any time; status for counts and suggestions.
reasonNoretire / false_alarm: why, in one line.
approveNopromote / retire: omit to request human approval in a form or Windows dialog. Optional terminal fallback: the human's 8-character code. Never guess it.
projectNoAbsolute project root (the folder holding brain.klypix and .klypix/). Defaults to this session's project brain.
include_candidatesNocheck: also run candidate rules — to see what a rule would catch before the human approves it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.108.1
    • changedInput schema / properties / approve / description
      Previous value: -"promote / retire: the human's 8-character code. Never guess or fabricate it."New value: +"promote / retire: omit to request human approval in a form or Windows dialog. Optional terminal fallback: the human's 8-character code. Never guess it."
    • changedInput schema / properties / block / description
      Previous value: -"promote: true only when the human printed the code with --block, making these rules stop an edit or a commit instead of warning. Rules warn by default."New value: +"promote: request blocking checks instead of warnings; the human reviews this severity in the approval prompt. With a terminal code, must match --block."
  2. Addedv1.107.1

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does: it discloses that rules WARN by default, that only human-approved --block stops an edit/commit, that --no-verify is recorded, that approve requires a human (never guess the code), and that checks are offline millisecond operations. That is genuinely behavioral detail beyond any structured field.

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

Conciseness3/5

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

Front-loaded with the core purpose, but the body is a dense wall of prose mixing actions, safety model, rule kinds, and host differences. Every clause is substantive, yet readability suffers; a structured list of actions would make it easier to scan.

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 14-parameter, 7-action tool with no output schema and no annotations, the description is nearly complete: it covers purpose, flow, safety, and partial return info (status reports fires/blocks/overrides/false alarms). Minor gaps remain in exact return shapes for add/promote, but the critical context is present.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the prose adds meaning the schema doesn't: include_candidates is 'to see what a rule would catch before approval', block must match --block with a terminal code, and approve omits the code to trigger human review. These clarify intent beyond the schema text.

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 opening sentence states a specific transformation ('turns lessons... into DETERMINISTIC diff checks'), names the artifact (.klypix/rules.json), and enumerates concrete rule kinds. It clearly separates itself from siblings by naming brain_sync and the edit hook as downstream consumers.

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

Usage Guidelines5/5

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

The 'Actions' tour plus the schema's action description give an explicit default flow (propose → add → (human) promote), say check can run 'any time', and specify status for counts and suggestions. It also states when rules block versus warn, and when include_candidates is appropriate.

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

Deploy Server

Other Tools