upkeep

Upkeep

English · 繁體中文 · 简体中文 · 日本語 · 한국어

An AI audit crew for your repo, installed as a skill. Upkeep dispatches focused AI reviewers in parallel to catch drift — stale docs, specs that no longer match the code, orphaned assets, broken conventions — and reports it with evidence before it compounds.

💳 No separate API bill. Upkeep runs on your existing Claude Pro/Max subscription — your logged-in claude CLI locally, or OAuth via claude setup-token in CI. No Anthropic API key, no per-token billing. And it's output-only: it reports drift with evidence and severity, but never edits or deletes your files.

Install

Claude Code — install as a plugin:

/plugin marketplace add wei18/upkeep
/plugin install upkeep@upkeep

Other agents (Cursor, Copilot, and any of the 70+ agents supported by skills):

npx skills add wei18/upkeep --skill upkeep-audit

Requirements: a logged-in claude CLI (Pro/Max), Node 20+, git — the engine runs on your machine in every install mode.

Then ask in any session:

Run an upkeep audit on /path/to/repo

On first use the skill clones the Upkeep engine into ~/.cache/upkeep and installs dependencies automatically. You get findings grouped by severity in chat, plus a self-contained HTML report.

What it does

• Scans a repository and dispatches a team of focused AI reviewers in parallel.
• Catches stale docs that drifted from code, specs that no longer match implementation, duplicate or orphaned files, convention violations, and out-of-sync translated docs.
• Reports divergence with evidence — it does not assume one artifact is always the source of truth.
• Never edits or deletes anything — output only.
• Produces a self-contained HTML report — and, when run in CI, a persistent GitHub tracking issue (upserted, never duplicated).

How it compares

Upkeep isn't a linter or a PR bot — it's a whole-repo, semantic drift auditor. Different tool, different job:

	Upkeep	Danger	Copilot / Cursor PR review
Looks at	The whole repo — docs, specs, assets, conventions	A PR's diff	A PR's diff
Finds	Semantic drift (README promises X, code does Y)	Rule violations you hand-write	Code issues in the diff
Rubric	Your repo's own conventions	Your custom rules	General code knowledge
Cadence	Scheduled or on-demand, repo-wide	Per PR	Per PR
Edits your code?	Never — output only	No	Suggests changes
Cost	Your Claude Pro/Max plan	Free (you write the logic)	Copilot/Cursor subscription

Run as a plain script

No agent at all? The same pipeline runs as a standalone script:

git clone --depth 1 https://github.com/wei18/upkeep ~/.cache/upkeep
cd ~/.cache/upkeep && npm ci
./scripts/local-audit.sh /path/to/repo --out ~/upkeep-report.html

Flag	Default	CI equivalent
--model	claude-opus-4-8	model
--rubric-lang	en	rubric_lang
--max-turns	30	max_turns
--out	./upkeep-report.html	report artifact

Requirements: a logged-in claude CLI (Pro/Max; no setup-token and no GitHub access needed), Node 20+, git.

Output: the same self-contained HTML report (upkeep-report.html by default) plus a terminal summary. Local runs never create GitHub issues.

Prefer a manual skill install? Copy skills/upkeep-audit/ into ~/.claude/skills/.

Automate it in CI

The same audit crew, on a schedule. Create .github/workflows/audit.yml in your repo:

name: repo audit
on:
  schedule:
    - cron: '0 3 * * 1'   # weekly, Monday 03:00 UTC
  workflow_dispatch:        # also run manually

permissions:
  contents: read
  issues: write
  id-token: write

jobs:
  audit:
    uses: wei18/upkeep/.github/workflows/audit.yml@v2
    with:
      model: claude-opus-4-8     # optional
      issue_label: audit         # optional; default: audit
      rubric_lang: en            # optional; reviewer language: en | zh-TW
    secrets:
      claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

Requirements

• A repo secret named CLAUDE_CODE_OAUTH_TOKEN — generate it locally with claude setup-token (available to Claude Pro/Max subscribers; usage counts against your subscription).
• The permissions block shown above (contents: read + issues: write + id-token: write).

Outputs