# repotector [Health: Active] **Category:** πŸ’» Developer Tools **Repository:** https://github.com/dir-ai/repotector **GitHub Stars:** 0 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/repotector ## Description The repo guardian AI agents handshake with before they touch your code. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "repotector": { "command": "npx", "args": ["-y","repotector"] } } ``` ## Documentation & README # Repotector ⬑ **The repo that remembers.** Every AI agent that visits your repo starts from zero: it re-derives the map, re-discovers the conventions, re-breaks the thing the last agent just fixed. Repotector gives the repo itself a memory. An arriving agent knocks at the front door, handshakes, and is handed the map, the standing decisions, and the last visitor's briefing; on the way out it signs the register. The next agent continues in two minutes instead of wandering for an hour β€” and a refactor doesn't quietly break what already works. Portable and self-contained: pure Node ESM, two dependencies (`@modelcontextprotocol/sdk`, `zod`). Works on any repo β€” JS/TS deeply, other stacks in honest orientation-lite. ## Install into any repo ```bash cd /path/to/your/repo npx repotector init ``` `init` scans the repo (never fails you on day one β€” see *grandfathered baseline* below), wires the MCP server into `.mcp.json`, and writes the doorway blocks so every arriving agent knows to handshake. It writes only inside `.repotector/` and inside `REPOTECTOR:BEGIN/END` markers β€” your prose and config are never overwritten. See [SECURITY.md](https://github.com/dir-ai/repotector/blob/HEAD/SECURITY.md) for the exact posture. Under `.repotector/`: | File | What it is | |-----------------|----------------------------------------------------------------------| | `intent.json` | The contract: standards, required paths, bounded contexts, canon rules. | | `atlas.json` | The map: exports/imports/purpose/kind per file, routes, components, stack, and a deterministic fingerprint. | | `dna.json` | Reverse-engineered entities + API contracts + intent. | | `baseline.json` | The grandfathered floor β€” the debt that existed on day one. | | `proof.json` | Gate verdict, regressions vs grandfathered debt. | | `register.jsonl`| The visitor ledger: who entered, when, what they touched, who's inside. | | `dna.inferred.json` | Reverse-DNA clauses for foreign repos (skipped when a `.psx/` mirror exists). | Plus, at the repo root, a regenerated **`JOURNAL.md`** β€” the diario di bordo, newest-first, that `handshake` serves the tail of so the next agent continues prior work instead of re-deriving it. ## The front door (handshake-first) The MCP server refuses deep tools until an agent calls `handshake` β€” and the `initialize` response already tells the agent to. In return the agent gets oriented in one call, and its exit is recorded for the next one. - **`handshake({ who, model?, purpose? })`** β€” orientation, ground rules, live gate verdict, map freshness, passport. Read-only and fast (no tree walk). - **`city_map()`** β€” intent, stack, built-vs-missing, brain pointers. On a non-JS repo it says *orientation-lite* instead of faking an empty map. - **`find_existing({ intent })`** β€” REUSE: does it already exist? Don't rebuild. - **`blast_radius({ changedFiles? })`** β€” PROTECT: transitive dependents + impacted routes/components. Omit `changedFiles` to use the git diff. - **`canon_check({ changedFiles? })`** β€” INTEGRATE: the repo's canon rules. - **`atlas_query({ query })`** β€” keyword search across the map. - **`quality_gates()`** β€” line-budget / structure / secret-hygiene, reported as regressions vs grandfathered debt. - **`register()`** β€” who's inside now and the full crossing log. - **`journal({ limit? })`** β€” the repo's recent story: what prior agents did and left unfinished. **`whats_next()`** β€” the sensible next work, derived from DNA gaps + open threads + TODOs, every suggestion citing its evidence. - **`dna_query({ clause?, topic? })`** β€” what the repo *specified* (authored from a `.psx/` mirror, or inferred, never merged). **`dna_coverage()`** β€” per clause: implemented / partial / missing. **`dna_diff({ changedFiles? })`** β€” which clauses a change touches. - **`depart({ summary? })`** β€” sign out; the git delta of your visit is recorded even if you forget the summary. Your summary becomes the next agent's briefing. ## Grandfathered baseline β€” never red on day one A guardian that fails your repo the moment you install it gets uninstalled the moment you install it. So `init` snapshots the debt that already exists (oversize files, tracked secrets, missing paths). Gates then fail **only on regressions** against that floor β€” a *new* offender, an offender that *grew*, a *new* leak. Pre-existing debt is reported loudly, never blocking. `repotector baseline` re-snapshots after you pay it down. ## v1.2 "Gatekeeper" β€” from advisor to checkpoint - **Commit guard** β€” `repotector hooks` installs a pre-commit that runs the gates; `gates` exits non-zero on regressions, so hooks and CI actually block. Grandfathered baseline means it never blocks day-one debt β€” only new damage. - **Protected paths** β€” `intent.protect.paths` globs (CI workflows, LICENSE…) that agents must not touch: change-based, never grandfathered, overridden only by editing the intent (an explicit, diffable act). - **Claims** β€” `claim({ paths })` declares your work zone; overlapping claims from live sessions answer `granted:false` with who/why. Advisory by design (blocking would be theater on a filesystem we don't control); claims die with the session. - **Decision records** β€” `depart({ decisions: [{ chose, over, because }] })` writes the *why* to the register and projects `DECISIONS.md`; the handshake serves standing decisions and `decisions_query` answers "was this deliberate?" β€” so agent 2 doesn't undo agent 1's choice. - **`repotector doctor`** β€” one command, semaphore answer to "how protected is this repo, really?", with a fix for every red. ## v1.5 "Mission" β€” the single verifiable chain The whole visit becomes one auditable contract: ``` handshake β†’ declare_mission β†’ (auto)claim β†’ work β†’ off-claim / forbidden reconciliation β†’ evidence pack (machine-verified vs agent-declared) β†’ depart β†’ the next agent inherits it all ``` - **`declare_mission({ goal, acceptance, claimPaths?, forbiddenPaths?, risk? })`** β€” bind the visit to a contract: your zone is auto-claimed (conflicts surfaced), and you get a one-shot briefing (gates, merge status, standing decisions, protected paths). - **Evidence pack at depart** β€” the register records what the MACHINE verified (gates verdict, trial-merge clean/conflicted, files touched, off-claim, forbidden violations) strictly apart from what the AGENT declared (per-criterion self-report); unreported criteria are listed, never assumed. "Done" becomes something the register can check, not a courtesy. - Other agents see missions in progress at handshake β€” what you're doing, not just where. ## v1.3 "Merge Guard" β€” commit without colliding - **merge_check** β€” a zero-damage TRIAL merge (git merge-tree) of HEAD against the integration base, run BEFORE you commit: reports clean/conflicted with the exact files, each attributed to who holds that zone (live claims β€” and, in PSX Workbench repos, the Merge Machine's leases via the .psx mirror). CLI: `repotector merge-check [target]` (exit 1 on conflicts, so hooks/CI can gate on it). Zero network: it trial-merges against your LOCAL refs and says so β€” fetch first for the freshest truth. ## Resilient register β€” agents die without signing out Sessions that enter and never leave (the agent was killed, the pipe closed) are auto-departed on the next handshake, with the git delta of what they touched. The ledger never fills with immortal open sessions, and a depart carries real work even when nobody called it. ## CLI ```bash npx repotector init # scan, wire .mcp.json, write the doors β€” day-one green npx repotector refresh # re-derive the map + re-stamp the doorway blocks npx repotector handshake # orientation + live gate + passport (logged visit) npx repotector city-map # built-vs-missing + brain pointers npx repotector dna-coverage # per specified clause: implemented / missing npx repotector whats-next # the sensible next work, with evidence npx repotector journal # the diario di bordo (regenerates JOURNAL.md) npx repotector gates # regressions vs grandfathered debt npx repotector baseline # re-snapshot the grandfathered floor npx repotector register # the visitor ledger npx repotector lock # optional passphrase gate on the deep map npx repotector mcp # start the stdio MCP server ``` ## Docker The image on GHCR wraps the CLI and the MCP server; the guarded repo is mounted, never baked in: ```bash docker run --rm -v "$PWD:/repo" ghcr.io/dir-ai/repotector init docker run --rm -v "$PWD:/repo" ghcr.io/dir-ai/repotector gates docker run -i --rm -v "$PWD:/repo" ghcr.io/dir-ai/repotector mcp # stdio MCP ``` Multi-arch (amd64/arm64), built and smoke-tested by CI on every release tag (see [Dockerfile](https://github.com/dir-ai/repotector/blob/HEAD/Dockerfile)). ## GitHub Action Guard a repo in CI with one step β€” grandfathered semantics apply, so the job fails only on regressions, never on day-one debt: ```yaml - uses: dir-ai/repotector@main with: command: gates # default; any CLI command works version: latest # pin an exact npm version for reproducible CI ``` ## Honesty Repotector guards repos, so it holds itself to its own standard. The lock is a compliance signal, not filesystem access control; the register is append-integrity, not tamper-proof; a static badge is self-reported. It spawns only `git`, makes no network calls, and pins exact versions in `.mcp.json`. The full threat model is in [SECURITY.md](https://github.com/dir-ai/repotector/blob/HEAD/SECURITY.md) β€” no security theater. ## Determinism The Atlas `fingerprint` is a SHA-256 over sorted source contents (16 hex chars), no timestamps β€” the same tree always fingerprints the same. Large files (>1MB, generated/minified) are marked, never read into the fingerprint. `builtAtHead` stamps the git sha so freshness can be checked without a walk. ## License MIT Β© PSX System. The core an agent needs in a repo is free forever; the compounding brain (Genome cloud, authored DNA) is the premium layer.