elizaos--eliza/plugins/plugin-gitpathologist/CLAUDE.md

@elizaos/plugin-gitpathologist

Forensic git-history analysis for Eliza agents: per-surface health timeline, drift inflection detection, and LLM-narrated rot post-mortem.

Purpose / role

This plugin adds git repository forensics to any Eliza agent running in a Node.js environment. It answers questions like "when did this code get bad?" or "where did rot start in src/payments/?" by walking git log, scoring each commit, detecting quality inflection points, and optionally calling the agent's configured small-text model to write a narrative explanation.

The plugin is opt-in: the elizaOS agent's plugin collector auto-loads the package when the workspace has a .git directory (and the platform is not mobile), unless ELIZA_GITPATHOLOGIST overrides that decision. ELIZA_GITPATHOLOGIST, GITPATHOLOGIST_BUDGET, and GITPATHOLOGIST_CACHE_DIR are all declared in the package's agentConfig.pluginParameters, but only GITPATHOLOGIST_BUDGET and GITPATHOLOGIST_CACHE_DIR are read inside this package; ELIZA_GITPATHOLOGIST is consumed by the agent runtime's plugin collector. The service itself performs no .git detection — GitPathologyService.start() registers unconditionally once the package is loaded.

Plugin surface

Kind	Name	What it does
Service	git_pathology (GIT_PATHOLOGY_SERVICE_NAME)	On-demand analysis orchestrator. Registers the pipeline and cache; all action calls go through it.
Action	GIT_PATHOLOGY	Multiplex action: action=report runs a full pathology analysis for a surface path/glob; action=list lists cached reports. Similes: ANALYZE_GIT_PATHOLOGY, GIT_HEALTH, GIT_FORENSICS, PATHOLOGY_REPORT, CODE_HISTORY_HEALTH, WHERE_DID_ROT_START.

No providers, evaluators, routes, or event handlers are registered.

Layout

src/
  index.ts                   Plugin object export; wires service + action
  types.ts                   All shared types: SurfaceSpec, AnalysisOptions,
                               RawCommit, ClassifiedCommit, CommitHealthPoint,
                               InflectionPoint, RotCause, PathologyReport,
                               CachedReportSummary, Operation
  render.ts                  Markdown renderer: PathologyReport → string
  secret-scrubber.ts         Regex-based secret redaction (API keys, tokens,
                               bearer headers, env-name=value patterns)
  actions/
    git-pathology.ts         GIT_PATHOLOGY action handler and parameter parsing
  services/
    git-pathology-service.ts GitPathologyService class; coordinates pipeline
  pipeline/
    scan.ts                  Step 1 — git log parsing (deterministic, no LLM)
    classify.ts              Step 2 — rule-based commit type + risk-flag tagging
    score.ts                 Step 3 — per-commit health delta + EMA scoring
    inflect.ts               Step 4 — peak and drift inflection detection
    narrate.ts               Step 5 — LLM narration for drift commits (optional)
  cache/
    report-cache.ts          Disk-backed JSON cache keyed by sha256(surface + '\0' + since)

Pipeline (scan → classify → score → inflect → narrate)

1. scan — calls git log --numstat once for the surface path/glob. No LLM. Returns RawCommit[].
2. classify — regex + prefix rules assign CommitType and riskFlags to each commit. Returns ClassifiedCommit[].
3. score — deterministic EMA scoring (α=0.3). Each commit gets a delta and running score. Reverts targeting commits within the lookback window apply a proximity penalty. Returns CommitHealthPoint[].
4. inflect — detects peaks (local EMA maxima) and drift onsets (sustained score drops ≥0.25 over 5 commits). Returns up to 5 peaks and 5 drifts as InflectionPoint[].
5. narrate — one ModelType.TEXT_SMALL call per drift, capped by budget. Fetches git show diff snippets (up to 8 KB, scrubbed of secrets) and asks the model to classify a RotCategory and write a 2-3 sentence narrative. Falls back to deterministic narration when the runtime has no model or budget=0.

Reports are cached by key = sha256(surface + '\0' + since). A cache hit is only valid when the repo HEAD sha matches the stored headSha.

Commands

All scripts require a built dist/ (run build first or use the repo-level turborepo pipeline).

bun run --cwd plugins/plugin-gitpathologist build         # Bun.build (ESM + CJS) + tsc declarations
bun run --cwd plugins/plugin-gitpathologist test          # vitest run
bun run --cwd plugins/plugin-gitpathologist typecheck     # tsgo --noEmit
bun run --cwd plugins/plugin-gitpathologist lint          # biome check --write --unsafe
bun run --cwd plugins/plugin-gitpathologist lint:check    # biome check (no write)
bun run --cwd plugins/plugin-gitpathologist format        # biome format --write
bun run --cwd plugins/plugin-gitpathologist format:check  # biome format (no write)
bun run --cwd plugins/plugin-gitpathologist clean         # rm dist .turbo

Config / env vars

Variable	Type	Required	Default	Description
ELIZA_GITPATHOLOGIST	boolean	No	auto	Force-enable (true) or force-disable (false) the plugin. When unset, plugin auto-enables if a .git directory is present.
GITPATHOLOGIST_BUDGET	number	No	20	Maximum LLM narration calls per analysis. Set to 0 to run fully deterministic (no model calls).
GITPATHOLOGIST_CACHE_DIR	string	No	<repoRoot>/.eliza/gitpathology	Override the cache directory. Relative paths are resolved against repoRoot.

The action reads ELIZA_WORKSPACE_DIR to resolve the repo root when running inside an Eliza agent workspace. Falls back to process.cwd() when it is unset.

How to extend

Add an action

1. Create src/actions/<name>.ts exporting a typed Action object.
2. Import it in src/index.ts and append it to gitpathologistPlugin.actions.
3. Add a test in __tests__/.

Add a pipeline phase

1. Create src/pipeline/<phase>.ts with a pure function (input: PreviousOutput[]) => NextOutput[].
2. Call it in GitPathologyService.runReport() (src/services/git-pathology-service.ts) after the appropriate existing phase.
3. Add or extend types in src/types.ts and re-export from src/index.ts if callers need the type.

Add a provider

1. Create src/providers/<name>.ts exporting a typed Provider object.
2. Import and push into gitpathologistPlugin.providers (currently an empty array).

Conventions / gotchas

• git binary required at runtime. The scan phase calls spawnSync("git", ...) directly. The plugin will fail to start meaningfully in environments without git on PATH.
• Node-only. exports.node is the sole distribution target. Do not add browser-compatible code paths.
• Secret scrubbing is mandatory before LLM calls and cache writes. narrate() runs scrubSecrets (string version) over every commit subject and diff snippet before they reach the model prompt; the service runs scrubSecretsDeep over the whole PathologyReport (including cached reads) before returning or writing to disk. Never bypass either.
• Cache is HEAD-keyed, not time-keyed. Any commit to the repo invalidates existing cache entries for that surface. This is intentional.
• Narrate falls back gracefully. If the runtime provides no useModel function or budget=0, narrate() uses deterministicRotCause() and logs a warning. The report is still valid.
• No background work. The service has no timers or subscriptions. Everything is on-demand via runReport().
• Logging prefix: [GitPathologyService], [GitPathology/narrate]. Use logger from @elizaos/core for all log output; see root AGENTS.md for the logger-only rule.

⛔ NON-NEGOTIABLE — evidence, trajectories & real end-to-end tests

The binding, repo-wide standard is AGENTS.md. Read it. Nothing in this package is done until it is proven done — a reviewer must confirm it works without reading the code, from the artifacts you attach. This applies to every feature, fix, refactor, and chore here. "Tests pass" is not proof; "CI is green" is not proof.

• Record AND read model trajectories. Capture the actual inputs and outputs of the model from a live LLM — not the deterministic proxy, not a mock: the prompt, the providers/context, the raw model output, every tool/action call, and the result. Then open the trajectory and review it by hand. A captured-but-unread trajectory is not evidence (packages/scenario-runner/bin/eliza-scenarios run <scenario> --report <out>).
• Real, full-featured E2E — no larp. Every feature ships detailed end-to-end tests that drive the real path end to end. Not the happy "front door" only: cover error paths, edge/empty/invalid input, concurrency, roles/permissions, and adversarial input. A test that asserts against a mock/stub/fixture standing in for the thing under test does not count. If the real model/device/chain/connector/account is hard to reach, make it reachable — that is the work, not an excuse to mock. If the existing tests here are shallow or mocked, fixing them is part of your change.
• Screenshots + logs at every phase, plus a complete walkthrough video/run-through of the entire feature or view, start to finish (bun run test:e2e:record).
• Manually review every artifact the change touches — never just the green check: client logs (console + network), server logs ([ClassName] …), the model trajectories in and out, before/after full-page screenshots, and the domain artifacts listed below for this package.
• No residuals. No shortcuts. The goal is not "done" — it is everything done. Clear every blocker by the hard path: build the real architecture, stand up the real model/device/service, actually test it. Never leave a TODO, a stub, a stepping-stone, or a "follow-up." When unsure, research thoroughly, weigh the options, and ship the best, highest-effort, production-ready version. Keep going until every possibility is exhausted.

Artifacts → attached inline in the PR (MP4 video, JPG screenshots, logs in <details>); attach each evidence type or explicitly mark it N/A with a reason — never leave it blank. If develop moved and changed behavior, re-capture evidence; stale proof is worse than none.

Capture & manually review for this package — CLI / tooling:

• The real command/flow invocation transcript (args in, stdout/stderr, exit code) and the artifacts it generated (files, scaffolds, manifests, screenshots/recordings).
• Failure paths: bad args, missing deps, partial state, permission/network errors.
• A recording/log of the actual run end to end — not a unit test of one helper.
• Any model interaction captured as a live trajectory and reviewed.