convez.ai
MCP ServerAutomaçãoIntermediário
xz1220

Kempt — Scanner de Débito Técnico para Agentes de IA

xz1220/Kempt

Diagnostica e limpa débito técnico de agentes IA com limpeza reversível

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que escaneia e limpa o estado local de agentes de codificação (Claude Code, Codex) detectando débito técnico invisível: memórias obsoletas, skills não utilizadas, conflitos de instruções e caches mortos. Oferece relatório de saúde (0-100), limpeza reversível via app desktop, CLI e skills de agent, com auditoria completa baseada em pesquisa.

Instalação

$npx convez-ai xz1220/Kempt

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Diagnosticar por que agentes Claude Code ficam lentos após meses de uso
  • Auditar memórias duplicadas, skills obsoletas e conflitos de instruções
  • Limpar caches e sessões mortas sem risco (tudo é reversível)

Veredito

Ferramenta especializada e bem-pesquisada para um problema real (agent debt) que afeta fluxos heavy de Claude Code. Implementação sólida com interface tripla (desktop/CLI/skills) e garantias de segurança (read-only por padrão, local-only, reversibilidade total). Nicho específico mas valioso para equipes que usam agentes de IA intensivamente.

README

A tradução para o português deste README ainda está na fila.

Kempt

Keep your coding agents kempt. The agent-debt scanner & reversible cleaner for Claude Code and Codex.

CI License: MIT Platform Node Tauri PRs Welcome

English · 简体中文


Use Claude Code or Codex heavily for a few months and your agent quietly gets slower, moodier, and weirder — and nobody can tell you why. The cause is agent debt: stale memories that get re-read every session, skills you installed once and never used (each one eats context budget), instructions that contradict each other across runtimes, and gigabytes of dead sessions and caches.

Kempt makes that invisible local state visible — then cleans it reversibly.

Why Kempt

  • 🔍 Read-only scan of ~/.claude and ~/.codex — never modifies, never follows symlinks, never reads secrets or active sessions.
  • 🧮 Research-grounded scoring, not vibes: a MemoryOS-style heat score decides whether a skill is actually idle (transcript references, engagement breadth, exponential recency decay — not just file age), SpamAssassin-style additive evidence explains every memory verdict with a visible rule trail, and the health score uses CVSS/CodeScene-style saturating aggregation so it never panics to 1/100. The papers and formulas live in docs/research.md.
  • ♻️ Everything is undoable. Cleaned items go to a retention-windowed recycle bin; one command (kempt restore --last) undoes the whole batch. The only hard delete is an explicit empty-recycle.
  • 🔒 Local-only. No login, no upload, no cloud calls at scan time. Telemetry is opt-in, counts-only, default off.
  • 🧰 Three surfaces, one engine — desktop app, CLI, and AI agent skills.

What it checks

DimensionWhat piles upWhy it hurts your agent
🧠 Memory pollutionStale / duplicated / contradictory entries in CLAUDE.md, memory filesRe-read every session; near-duplicates are the #1 hallucination trigger (Context Rot)
🧰 Tool overlapSkills / MCP servers / commands you never useEvery catalog entry eats context budget (RAG-MCP)
⚔️ Instruction conflictClaude Code and Codex configs fighting each otherConflicting instructions degrade output quality (ConInstruct)
👻 Runtime residueOrphan daemons, dead PID files, leftover locksBackground cost, startup weirdness
🗑 Reclaimable junkOld sessions, caches, logsPure disk waste — safely recyclable

Three ways to use it

1 · Desktop app

A calm, forensic macOS app (Tauri shell, ~5 MB, with the engine ported to Rust).

git clone https://github.com/xz1220/Kempt.git && cd Kempt
npm install && npm run build
npx tauri build   # → src-tauri/target/release/bundle/macos/Kempt.app (+ .dmg)

2 · CLI

The same engine in your terminal — and in your cron jobs and CI.

npm install && npm link     # installs the `kempt` command

kempt scan                  # read-only scan → report (exit 3 with --fail-under <score>)
kempt plan                  # what would be cleaned, grouped & sized
kempt clean                 # dry run (default!) — add --yes to apply
kempt restore --last        # undo the entire last batch
kempt history               # recycle-bin batches, what's still undoable
kempt settings set telemetry off

Every command takes --json for scripting and --lang zh|en for the UI language.

3 · AI agent skills

Let your agent run its own checkup. Two Claude Code skills ship in skills/:

cp -r skills/kempt-checkup skills/kempt-clean ~/.claude/skills/
  • kempt-checkup — read-only diagnosis: scans, explains the report in plain language, never cleans.
  • kempt-clean — guided cleanup: dry-run first, asks for explicit confirmation, always ends with the undo path. Hard rules forbid it from hard-deleting anything.

Then just ask: “why does my agent feel slow?” or “clean up my agent debt”.

How the scoring works

graph LR
  subgraph engine["One engine · two equivalent ports (TypeScript + Rust)"]
    S["Scanner<br/>read-only, symlink-safe"] --> A["Analyzer<br/>heat · evidence · health"]
    A --> P["Clean plan<br/>safe / manual groups"]
    P --> C["Cleaner<br/>reversible moves"]
    C --> R[("Recycle bin<br/>batch undo · retention")]
  end
  GUI["Desktop app<br/>(Tauri, 5 MB)"] --> engine
  CLI["kempt CLI<br/>--json · --fail-under"] --> engine
  SK["Agent skills<br/>kempt-checkup · kempt-clean"] --> CLI
  • Skill heat = ln(1+refs) + ln(1+sessions) + e^(−age/30d) — MemoryOS's heat formula fed by actual transcript references, so a skill you used yesterday is never flagged just because its file mtime is old. On a real machine this cut false positives from 34 “unused” skills to 4.
  • Memory evidence — additive weighted rules (DEAD_REF +2.5 · STALE_90D +1.5 → 4.0) with the fired-rule trail shown in the UI, SpamAssassin-style.
  • Health score — 100 × (1 − Σ wᵈ·sat(loadᵈ)) with per-dimension saturating curves; weights favor what changes agent behavior (memory .30, conflict .25) over what merely wastes resources.

Full literature review, formulas, and the honesty statement about which constants are research-backed vs engineering judgment: docs/research.md.

The safety contract

  1. Scanner is read-only — never modifies, never follows symlinks, never reads auth.json / secrets/ / keys.
  2. Cleaning is reversible — recycle bin with retention (7/30/90 days), batch undo, no implicit hard deletes.
  3. Local-only — content never leaves your machine; desktop API binds loopback with a per-launch session token + Host/Origin checks (anti-DNS-rebinding).
  4. Agent homes only — Kempt never touches paths outside ~/.claude, ~/.codex, and its own ~/.kempt.

Validated by adversarial CodeX ↔ Claude review workflows (3 rounds, 29 real defects fixed before release) plus 70+ automated tests across both engine ports.

Development

npm install          # also builds the CLI (bin/kempt.mjs)
npm run dev          # Vite UI :5174 + Express API :8787
npm test             # vitest: engine / HTTP / CLI / skills / components
npx tsc --noEmit
cd src-tauri && cargo test --lib

See CONTRIBUTING.md for the project layout and ground rules. 中文 issue / PR 完全欢迎。

License

MIT © 2026 danielxing

Ver o original no GitHub

Bom para

Relacionados