opty

Why opty exists

AI coding agents read repo-local markdown and config files as their working instructions. Over months, these files grow stale. Duplicates creep in. Secrets get pasted for "just a second" and forgotten. Files swell past the context window until the agent can only read half of what you wrote.

Then the agent commits a secret you thought you deleted, or ignores a rule buried past a real instruction cutoff, and you spend an afternoon figuring out why.

opty is a linter for that problem. It scans your agent files, grades them A–F, fixes what's safe to fix, and backs up every change before it touches anything.

When you need enforcement, opty verify compares repo rules against git and workflow evidence.

What it scans

Examples above are representative, not exhaustive. opty scan reads the files present in the chosen scope, and opty doctor discovers current, global, and workspace roots before you target one.

Commands

For commands with [path], omit the path to use the current directory. Pass a file or directory only when you want to audit another target.

opty init <platform>

Scaffold a baseline config for claude or openclaw.

opty scan [path]

Inventory one repo path or file, surface issues, and print a human report.

opty doctor [path]

Discover current, global, and workspace scopes from known roots. Add --stack, --json, or --audit when another agent needs scope context.

opty score [path]

Calculate a quality score (0–100) and a grade (A–F).

opty diff [path]

Render a colored before/after diff of the changes opty fix would make, with score delta context — nothing is written. Use --tool or --scope to target a discovered scope.

opty fix --dry-run

Preview what will be fixed — nothing is written.

opty fix [path]

Apply safe fixes to one path or a discovered scope. A backup is written to .opty/backups/.

opty restore [path]

Roll back the last fix from backup. Use --id <ts> for a specific snapshot, or point at the scoped root you fixed.

opty verify [path]

Compare repo rules against git history and workflow evidence when you need enforcement. --fail-on-violations exits 2 on violation.

opty score --share [path]

Emit a 1200×630 score card for launch posts, social sharing, or changelog screenshots.

opty badge [path]

Emit a README-ready SVG badge in flat, compact, or pill styles.

Docs for agents

Use JSON when another agent needs receipts instead of terminal prose. The human entry point is opty scan; the agent discovery entry point is opty doctor --json.

mkdir -p .opty
opty doctor --json > .opty/doctor.json
opty scan --json > .opty/scan.json
opty fix --canary --json > .opty/canary.json
opty score --json > .opty/score.json
opty verify --json > .opty/verify.json

Claude Code, Codex, OpenCode, OpenClaw, Goose, Hermes, Kilo, or CI jobs can read those files directly.

Paste into your agent

Audit this repo's AI agent configuration with opty.

Run these commands first:

mkdir -p .opty
npx optymd doctor --json > .opty/doctor.json
npx optymd scan --json > .opty/scan.json
npx optymd fix --canary --json > .opty/canary.json
npx optymd score --json > .opty/score.json
npx optymd verify --json > .opty/verify.json

Read the JSON files, not terminal prose. Summarize:
- discovered current, global, and workspace scopes
- default next target for each tool from toolReports[].effectiveTarget
- score and grade
- critical issues and warnings
- safe fixes opty can apply and whether the canary improved or warned
- verify rule violations, if any

Do not run opty fix without --canary yet. First explain the planned changes, canary result, backup path that will be created, and ask before editing.
If I ask for one tool, use that tool's toolReports[].effectiveTarget to rerun scan/score with --tool <tool> --scope <scope>, plus --index only when effectiveTarget.index > 1.
Use doctor --tool <tool> --audit --json only when you need a compact quality snapshot for one discovered tool chain.

Example report

$ opty scan

  opty scan — claude
  _______________________________________________________

  6 files  |  Score: 72 / B  |  1 critical  4 warnings

  CONTEXT LIMITS
  x  BOOTSTRAP.md                  12500 / 12000 chars  (4% over)

  DEAD REFERENCES
  !  skill.md            (referenced 2x)
  !  tailwind.config.js
  !  heartbeat.md

  NOTABLE FILES
  A  CLAUDE.md                       92    no issues
  B  skills/drizzle-ops/SKILL.md     74    no issues
  D  CLAUDE.local.md                 47    2 minor

  BY TYPE
  agent    2 files   avg  ########------  70
  skill    3 files   avg  ######--------  53

  FIX PRIORITY
  1. Trim 1+ files exceeding platform limits
  2. Remove 4 dead file references
  3. Add scope boundaries to 2 skills

What gets scored

Per-file — agent (CLAUDE.md, AGENTS.md)

Fleet-level checks

Each one scales the overall score up or down based on whether the project-wide pattern holds:

• role coverage — are required files present?
• role separation — are files doing distinct jobs?
• content coherence — no cross-file contradictions
• codebase awareness — blind spots documented
• reference integrity — no dead file references
• token budget — within context window and platform size limits
• skill routing — no conflicting skill trigger domains
• injection control — files properly mapped to injection paths

Auto-fix behavior

opty fix applies only safe, reversible changes. Every run writes a timestamped backup to .opty/backups/. Undo with opty restore, or point opty restore <path> at the discovered scope you touched.

• Replace leaked API keys with environment variable placeholders.
• Replace connection strings with $DATABASE_URL.
• Replace chmod 777 with chmod 755.
• Remove duplicate paragraphs within a file.
• Shorten verbose phrases ("in order to" → "to").

GitHub action

- uses: AytuncYildizli/opty/action@v1
  with:
    path: .
    fail-below: 50

Use mode: verify with fail-on-violations for CI rule enforcement:

- uses: AytuncYildizli/opty/action@v1
  with:
    path: .
    mode: verify
    fail-on-violations: true

Install

npm install -g optymd

Or one-off:

npx optymd scan
npx optymd scan AGENTS.md