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 --human init <platform>

Scaffold a baseline config for claude or openclaw.

opty agent scan|plan|verify [path]

Emit versioned sanitized evidence, a non-executable plan, or deterministic verification for an AI host.

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 for direct-human diagnostics. Raw JSON is not an AI handoff.

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 --human fix [path]

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

opty --human 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 the versioned opty agent namespace for AI hosts. Legacy JSON reports can contain raw content and paths, so they remain direct-human or trusted-CI diagnostics.

opty agent scan .
opty agent plan .
# after separately approved host-owned edits
opty agent verify .

Do not ask an AI host to open raw report files. Host-visible output and opened files are already AI-sharing channels.

Paste into your agent

Audit this repo's AI agent configuration with opty.

Run these commands first:

npx optymd@latest agent scan .
npx optymd@latest agent plan .

Read only the sanitized envelopes. Summarize platform coverage, aggregate
severity/category counts, uncertainty, and opaque target tokens. Do not ask
OPTY for raw file content or paths, and do not invoke legacy fix, restore,
init, install, enrichment, or raw scan JSON commands from this AI host.

If I separately ask you to edit with your own host tools, use your normal
permission model. Then run `npx optymd@latest agent verify .` and summarize the
new deterministic aggregate result. OPTY itself remains read-only here.

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 --human fix retains the deprecated direct-human compatibility path for safe, reversible changes. Every run writes a timestamped backup to .opty/backups/. Undo with opty --human restore, or point opty --human 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

For agents

opty runs as a priced agent too: the score rails are a plain HTTP GET, so another agent can grade a repository and pay for the answer without a human in the loop.

curl "https://api.opty.md/v1/score?repo=anthropics/claude-code"

Say hello at /hello, or read the machine-readable agent card.

On the board

No agents on the board yet.