Audits and code reviews for coding agents

oy adds repeatable, deterministic-input audit and review workflows to the coding agent you already use. The workflows ship as standard Agent Skills under .agents/skills, which OpenCode, Cursor, Codex, Copilot, and Gemini CLI all read natively.

Use it to:

• audit a repository and write ISSUES.md or SARIF;
• review a workspace or git diff <target> and write REVIEW.md;
• fix one reported finding, verify it, and rerun the review.

The simple mental model

oy selects and freezes the review input
  → your agent analyzes it with your model and permissions
  → oy validates and writes the report

This prevents silent model-selected sampling and makes the reviewed input visible. Findings are still model-generated and can vary.

Start here — 3 steps

1. Install

curl -fsSL https://oy.adonm.dev/install.sh | sh
oy doctor --check   # expect "global skills ok"

2. Finish setup in your agent — copy-paste:

run the oy-setup skill to finish setup

The skill checks that your agent can see oy-audit, oy-review, oy-enhance, and copies them to your host’s preferred location if needed (for example .claude/skills).

3. Create your first report

audit this repository with the oy-audit skill

Look for ISSUES.md in the workspace root. Then try:

review the diff against main with the oy-review skill
use the oy-enhance skill to fix audit-0123456789abcdef

First time? Follow the full walkthrough in Getting started — it explains what each step does and what to do if something fails.

New to Agent Skills?

Agent Skills are plain Markdown files (SKILL.md). oy setup writes four of them to ~/.agents/skills/:

• oy-audit, oy-review, oy-enhance — the workflows
• oy-setup — verifies installation and installs the oy persona

Your agent loads the matching SKILL.md when you mention it. No extra daemon, no API keys stored by oy.

What oy owns

• gitignore-aware repository and target-diff collection;
• ordered evidence files and explicit coverage limits;
• changed-input and artifact-integrity checks;
• normalized Markdown/SARIF reports with stable finding IDs;
• skill installation and legacy OpenCode plugin migration.

What your agent owns

• models and provider credentials;
• permissions and approvals;
• shell, edit, web, and other tools;
• sessions, UI, and model execution.

The skills run under your agent’s own permission model and never broaden it. oy is not a sandbox; see the security policy.

Choose your next page

• Getting started — install and create a first report (start here if you’re new)
• Workflow guide — choose scope, understand findings, and remediate
• Examples and CI — inspect reports and upload SARIF
• Troubleshooting — fix the 6 most common first-run problems
• CLI reference — exact commands, setup behavior, and environment variables
• Compatibility — supported platforms and agent hosts
• Security policy — trust and disclosure boundaries

Getting started

New here? TL;DR — 2 minutes:

curl -fsSL https://oy.adonm.dev/install.sh | sh  # installs oy + skills, choose Global
oy doctor --check                                  # should say "global skills ok"
# then in Cursor / OpenCode / Codex / Copilot, say:
# "run the oy-setup skill to finish setup"
# "audit this repository with the oy-audit skill"

This guide installs oy, verifies it, and creates your first report. Follow it top-to-bottom the first time — later runs are just one line to your agent.

Before you begin — checklist

You need:

• OS: Linux or macOS (use WSL2 on Windows) — check with uname -a
• Agent: any that reads Agent Skills — OpenCode, Cursor, Codex, Copilot, or Gemini CLI
• Model provider: configured in your agent (for example an API key in Cursor/OpenCode settings). oy never stores credentials.
• git only if you plan to review a diff against a branch (e.g. main)

Not sure if your setup qualifies? See Compatibility for tested versions.

1. Install oy

Recommended: one-line installer

curl -fsSL https://oy.adonm.dev/install.sh | sh

When prompted, choose Global unless you only want oy in the current repository.

To skip the prompt (for scripts or CI):

curl -fsSL https://oy.adonm.dev/install.sh | sh -s -- --global
curl -fsSL https://oy.adonm.dev/install.sh | sh -s -- --workspace  # current repo only

What the installer does:

1. Installs mise (if missing) with its official bootstrap for bash/zsh/fish;
2. Installs a prebuilt oy release with mise;
3. Installs prebuilt tokei and Universal Ctags context helpers (optional, for large repos);
4. Runs oy setup, which writes the skills to ~/.agents/skills/ and removes any legacy OpenCode plugin state.

Tip: Review install.sh before piping to a shell. Set OY_INSTALL_SCOPE=global|workspace as an alternative to flags, or OY_SKIP_SETUP=1 to install binaries without changing skills.

Alternative installs

With mise (no curl pipe):

mise use --global --yes --minimum-release-age 0 github:adonm/oy-cli@0.15.2
mise exec github:adonm/oy-cli@0.15.2 -- oy setup

From source (requires Rust 1.96+):

cargo install oy-cli --locked
oy setup

The installer and oy doctor --install-missing use aqua:XAMPPRocky/tokei@12.1.2 and release-only archives from github:universal-ctags/ctags-nightly-build — no Rust toolchain needed.

2. Verify and finish agent setup

Check the CLI:

oy --version        # should print 0.15.x
oy doctor --check   # should print "global skills ok" or "workspace skills ok"

If oy doctor --check says skills are missing, run:

oy setup            # writes to ~/.agents/skills
# or for this repo only:
oy setup --workspace
oy doctor --check   # check again

Finish inside your agent — copy-paste this prompt:

run the oy-setup skill

What the skill does:

• Confirms your agent can discover oy-audit, oy-review, oy-enhance, oy-setup from ~/.agents/skills or .agents/skills;
• If your agent prefers a different directory (for example .claude/skills for Claude Code), it offers to copy or symlink the skills there;
• Installs the oy persona (improves your default agent or creates an oy agent) and reruns oy doctor --check.

You only do this once per machine (or per workspace if you used --workspace).

3. Understand setup scope (pick one, don’t overthink)

For most new users: use Global. The installer’s --workspace flag is separate — it controls where mise writes tool versions, not where skills go.

Setup backs up any oy-owned files before changing them and leaves user-modified skill files untouched (it only overwrites files with <!-- Generated by oy setup -->). See Setup ownership.

4. Create your first report

Pick a small or medium repository for your first run — you’ll get faster feedback and avoid the 80-chunk limit.

Audit (security-focused):

audit this repository with the oy-audit skill

Look for ISSUES.md in the workspace root. Open it — you’ll see a verdict, a findings summary with IDs like audit-abc123..., detailed evidence with file paths, and a machine-readable JSON block at the bottom.

Review (code-quality):

review this repository with the oy-review skill     # whole workspace
review the diff against main with the oy-review skill   # only changes vs main

Look for REVIEW.md. Target-diff reviews need git and a valid ref (branch, commit, tag).

Fix one finding:

use the oy-enhance skill to fix audit-0123456789abcdef

Use the real ID from your report. The skill checks the cited source, makes one minimal fix, and runs the narrowest verification available. Then rerun the same audit/review to confirm — the report will carry forward or drop the finding.

5. What to expect

• Evidence is frozen: oy writes ordered chunks under .oy/runs/<run-id>/ and the model must read every chunk.
• Reports are generated: ISSUES.md / REVIEW.md / oy.sarif are overwritten on each run. Treat findings as candidates until you confirm the evidence.
• No silent sampling: if the repo exceeds 80 chunks, oy fails instead of sampling. Narrow the path first (e.g. audit src/auth).

Read the exclusions before relying on a report: gitignored/hidden files, target/node_modules/.tmp, lockfiles, secrets, binary or >512 KiB files are skipped. See Coverage and limits.

If something fails — quick fixes

Still stuck?

oy doctor --json | head -n 100   # redacted diagnostic output — safe to share
oy setup --dry-run               # preview what setup would change

Include oy --version, your agent + version, OS/architecture, and redacted oy doctor --json when asking for help (see Compatibility).

Next steps

• Workflow guide — choose scopes (path vs focus), understand statuses (new, fixed?, stale), and remediation loops
• Examples and CI — see real ISSUES.md / REVIEW.md / SARIF snippets and GitHub Actions upload
• Troubleshooting — expanded fixes with copy-paste commands
• CLI reference — every command, environment variable, and file layout

Workflow guide

First time? Start with one line to your agent: audit this repository with the oy-audit skill — then come back here to understand scope, findings, and the fix loop.

Your agent picks the matching skill from .agents/skills (or ~/.agents/skills) and runs its protocol: prepare evidence, read every chunk, write candidates, and finalize the report.

Your first audit — step by step

1. Pick a small folder to start fast and avoid the 80-chunk limit:

   audit src/auth with the oy-audit skill
   

2. Open ISSUES.md in the workspace root. You’ll see:
   • a header with the oy audit prepare command and date
   • Findings summary — one line per finding with ID, severity, and file location
   • Detailed findings — evidence, impact, and fix guidance
   • Machine-readable block — oy-findings JSON with stable IDs for reruns
3. Treat findings as candidates until you confirm the evidence and impact — they are model-generated.
4. Rerun after a fix — the next audit carries forward still-current findings, marks others stale or fixed?, and keeps IDs stable.

Choose what to review

Audit scope and focus

When you ask for an audit, oy interprets your words two ways:

Rule: a single existing workspace-relative path becomes the collection scope. All other text guides the model without narrowing collection.

Examples:

audit this repository
audit src/auth
audit the authentication boundaries
audit src/api focusing on input validation

Review scope and focus

review this repository
review the diff against main
review the diff against HEAD~3, focusing on error handling

• A branch, commit, tag, or ref selects target-diff review — only the diff is collected (great for PRs).
• Omit the target for a whole-workspace review.
• Add focus text (e.g. “focusing on error handling”) to guide the reviewer without changing scope.

Review findings are intentionally sparse. The reviewer prefers concrete structural issues — unclear ownership, unnecessary complexity, weak boundaries/types, expensive dependencies, or files near 1000 lines needing decomposition — over generic advice.

Path vs focus — cheat sheet

# path (narrows what oy collects)     vs     focus (guides what model looks for)
audit src/auth                                 audit focusing on auth
review src/cli                                 review focusing on error handling
# combine both:
audit src/auth focusing on session handling
review the diff against main focusing on types and boundaries

Read a report

Markdown reports contain:

• a verdict or summary;
• detailed evidence-backed findings;
• a machine-readable oy-findings JSON block;
• generation and evidence metadata (digest, chunk count, date).

Each finding has a stable ID (audit-... or review-...), severity (High/Medium/Low/Info), status (new, carried-forward, fixed?, stale), location when available, evidence, and remediation guidance.

A no-findings report is success, not failure — check the exit status and metadata to tell the difference. It will have an empty JSON array and a verdict like “No major structural concerns.”

Fix and confirm one finding

Ask your agent to fix a finding with the oy-enhance skill, ideally by ID:

use the oy-enhance skill to fix audit-0123456789abcdef
use the oy-enhance skill to fix review-0123456789abcdef

The skill reads ISSUES.md or REVIEW.md, confirms the cited source in code, fixes one actionable finding with the smallest correct change, and runs focused verification. It never broadens permissions; if a needed check is denied, it reports the remaining check.

Then rerun the originating audit or review. The new report replaces the old one, carries forward findings that still apply, and drops stale ones. Use the stable ID to track a finding across reruns.

Hit the chunk limit?

The default limit is 80 evidence chunks. If preparation exceeds it, oy fails instead of silently sampling — this is intentional.

Fix it in order:

1. Narrow the path first (best):

   audit src/auth with the oy-audit skill
   audit src/api with the oy-audit skill
   

2. Raise --max-chunks only when the broader scope is intentional — your agent can pass it via the skill, or you can call oy audit prepare --max-chunks 120 directly for automation.

Large files and diffs are split into bounded chunks automatically; you don’t need to chunk manually.

What happens under the hood

Audit and review follow four stages:

1. Prepare — collect eligible workspace files or a target diff into ordered chunks under .oy/runs/<run-id>/.
2. Review — the agent reads every prepared chunk under your current model and permissions.
3. Verify — reject changed inputs, modified evidence, concurrent output changes, or malformed finding data.
4. Finalize — write normalized Markdown or SARIF.

Collection and report normalization are deterministic. Model findings and prose are not.

Advanced automation can call oy audit|review prepare and finalize directly; most users should just use the skills.

Coverage and limits

The workspace collector excludes:

• gitignored and hidden paths;
• .git, .oy, target, node_modules, .venv, and .tmp;
• common lockfiles, generated reports, likely secrets, and private-key formats;
• binary, non-UTF-8, empty, unreadable, and larger-than-512-KiB files.

These exclusions reduce accidental disclosure and context waste, but they also limit completeness. In particular, an oy audit is not a complete supply-chain audit because lockfiles are excluded.

Eligible large files and diffs are split into bounded chunks. Prepared source may be sent to the model provider configured in your agent — see SECURITY.md.

Practical guidance

• Begin with a small scope and inspect the first report before going wider.
• Narrow by path before raising --max-chunks.
• Use a model with reliable tool use and sufficient context.
• Do not rely on secret-like filenames as a security boundary.
• Keep generated reports private when their findings or paths are sensitive.
• Pin OY_OPENCODE_MODEL=provider/model#variant when comparing repeat runs.
• Prefer one finding per oy-enhance pass — fix, verify, rerun.

See Examples and CI for representative output and SARIF upload, and Troubleshooting if a workflow fails.

Examples and CI

New? Start with audit this repository with the oy-audit skill — the snippets below show what the generated reports look like so you know what to expect.

The reports below are illustrative. Paths, IDs, wording, and findings depend on the reviewed code and selected model.

Audit with one finding

Prompt to your agent:

audit this repository with the oy-audit skill, focusing on authentication boundaries

Shortened ISSUES.md (look for this file in your workspace root after the run):

# Audit Issues

> Generated with [oy-cli](https://crates.io/crates/oy-cli): `oy audit prepare --focus 'authentication boundaries'` · 2026-07-13

## Findings summary

- `audit-2a71...` **High** `src/auth.rs:84` — Session lookup accepts an unscoped tenant ID _(status: new; fix: use the `oy-enhance` skill targeting `audit-2a71...`)_

## Detailed findings

### [High] Session lookup accepts an unscoped tenant ID

Evidence: `src/auth.rs:84` uses the caller-provided tenant before authorization.

## Machine-readable findings

```json oy-findings
[
  {
    "id": "audit-2a71...",
    "status": "new",
    "source": "audit",
    "severity": "High",
    "title": "Session lookup accepts an unscoped tenant ID",
    "locations": [{"path": "src/auth.rs", "line": 84}],
    "evidence": "Caller-provided tenant reaches session lookup before authorization.",
    "body": "Bind tenant scope to the authenticated principal before lookup.",
    "category": "access-control"
  }
]
```

The Markdown is for people; the JSON block preserves finding IDs and state for reruns and the oy-enhance skill. Copy the ID (e.g. audit-2a71...) to fix it:

use the oy-enhance skill to fix audit-2a71...

Target-diff review

Great for pull requests — only the changed code is reviewed.

review the diff against main with the oy-review skill, focusing on types and boundaries

Shortened REVIEW.md:

# Code Quality Review

## Verdict

Needs work.

## Findings summary

- **Medium** — Two structs represent the same persisted state (`src/cli/config.rs:41`).

## Detailed findings

### [Medium] Two structs represent the same persisted state

Both structs are serialized independently. Keep one persisted representation and convert at the boundary.

## Machine-readable findings

```json oy-findings
[{"id":"review-7bd1...","status":"new","source":"review","severity":"Medium","title":"Two structs represent the same persisted state","locations":[{"path":"src/cli/config.rs","line":41}],"evidence":"Both structs are serialized independently.","body":"Keep one persisted representation.","category":"state-ownership"}]
```

No target → whole workspace is reviewed. With a target (main, HEAD~3, a commit SHA), only that diff is collected.

Successful no-findings review

This is success, not failure — the run passed and nothing high-conviction was found:

# Code Quality Review

## Verdict

No major structural concerns.

## Findings summary

No high-conviction findings.

## Machine-readable findings

```json oy-findings
[]
```

A failed run exits nonzero or does not finalize the report at all. Check the CLI exit status and the header metadata (digest, chunk count) to tell the two apart.

Fix and confirm

use the oy-enhance skill to fix audit-2a71...
# Inspect the source diff and verification output, then rerun the same audit:
# "audit this repository with the oy-audit skill, focusing on authentication boundaries"

The second audit should drop the finding if it no longer applies or update its lifecycle state (new → fixed? → stale → gone) from current evidence. Always rerun the originating workflow to confirm.

SARIF

The oy-audit skill writes SARIF when you ask for sarif output:

audit this repository with the oy-audit skill, using sarif format and writing oy.sarif

The CLI normalizes SARIF 2.1.0 with rules, locations, severity, and provenance. Inspect it before upload, especially when repository paths or finding text are sensitive.

GitHub code scanning

Agent-backed audits need the agent and its provider configured in CI. Use protected secrets and do not expose privileged credentials to untrusted pull-request code.

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
  - uses: jdx/mise-action@e6a8b3978addb5a52f2b4cd9d91eafa7f0ab959d # v4.2.0

  - name: Install oy
    run: |
      mise use --global --yes --minimum-release-age 0 github:adonm/oy-cli@0.15.2
      mise exec github:adonm/oy-cli@0.15.2 -- oy setup

  - name: Run audit with an agent
    env:
      # Replace with the environment variable required by your agent's provider.
      PROVIDER_API_KEY: ${{ secrets.PROVIDER_API_KEY }}
    run: |
      opencode2 run "Load the oy-audit skill and audit this repository with sarif output." --format json
      # Or use your CI's agent CLI (Cursor CLI, Codex, etc.) the same way.

  - name: Upload SARIF
    if: always() && hashFiles('oy.sarif') != ''
    uses: github/codeql-action/upload-sarif@v4
    with:
      sarif_file: oy.sarif

Pin versions in production CI and configure the provider in your agent of choice. oy does not upload reports itself.

Tips for new users

• Start narrow: audit src/auth is faster and cheaper than audit this repository on a large codebase
• Read the evidence: every finding should cite a path/line/symbol — if it doesn’t, treat it skeptically
• One fix at a time: let oy-enhance handle one ID, verify, rerun — don’t batch unrelated fixes
• Compare runs: set OY_OPENCODE_MODEL=provider/model#variant to keep model choice explicit across reruns

Troubleshooting

This page covers the most common first-run problems and their fixes. For setup details see Getting started; for report interpretation see Workflow guide.

Quick diagnosis

Run this first — it tells you what oy sees:

oy doctor --check
oy doctor --json | head -n 80   # redacted, safe to share
oy --version

1. oy: command not found

Cause: mise hasn’t activated in this shell, or ~/.local/bin isn’t on PATH.

Fix:

# restart your shell, or:
exec $SHELL -l
oy --version

# if still missing, check where mise put it:
mise exec github:adonm/oy-cli@latest -- oy --version
echo $PATH | tr ':' '\n' | grep -E "mise|\.local/bin"

The installer configures mise activation for bash/zsh/fish via mise use. After install, you need a new shell session.

2. oy doctor --check says skills are missing

Fix:

oy setup                # global: ~/.agents/skills
oy doctor --check       # should now say "global skills ok"

# per-repo only:
oy setup --workspace
oy doctor --check       # should say "workspace skills ok"

Check the files exist:

ls ~/.agents/skills/oy-audit/SKILL.md
ls ~/.agents/skills/oy-review/SKILL.md
ls ~/.agents/skills/oy-setup/SKILL.md

If OY_SKILLS_DIR is set, it overrides ~/.agents/skills — check echo $OY_SKILLS_DIR and oy doctor --json.

3. Agent says “skill not found” even though oy doctor --check passes

Different agents look in slightly different places:

Fix: ask your agent to run the oy-setup skill — it offers to copy or symlink the canonical skills to the host-specific directory:

run the oy-setup skill

See Compatibility for details.

4. Model not responding / authentication error

oy never handles API keys. Your agent does.

• Cursor: Settings → Models → add provider API key
• OpenCode: ~/.config/opencode/opencode.jsonc or .opencode/opencode.jsonc with provider credentials
• Codex / Copilot / Gemini CLI: configure the provider in that host’s settings

Test your model without oy first (ask the agent a simple question). If that fails, fix provider config before auditing.

5. exceeds max-chunks 80 or “coverage limit”

The repo is larger than the default 80-chunk budget. oy fails closed rather than silently sampling.

Fix — narrow the scope first:

audit src/auth with the oy-audit skill
audit src/api with the oy-audit skill
review src/cli with the oy-review skill

Only raise the limit when the broader scope is intentional:

audit this repository with the oy-audit skill with max-chunks 120

Or for automation: oy audit prepare --max-chunks 120.

6. Target-diff review fails (not a git repository / unknown ref)

• Must be inside a git repo: git status
• Target must exist: git rev-parse --verify main (or origin/main, a commit SHA, tag)
• Try git fetch origin if the target is a remote branch
• Omit --path when using a target — the diff already scopes the input

7. Empty or “no findings” report — is it broken?

No — an empty findings array is a successful run:

## Findings summary
No high-conviction findings.
```json oy-findings
[]
```

Check the report header for evidence digest and chunk count, and the CLI exit code (0 = success). Try a more focused prompt or a larger scope if you expected findings.

8. Reports don’t appear / wrong location

Default outputs are workspace-relative and must stay inside the workspace:

• ISSUES.md for audits
• REVIEW.md for reviews
• oy.sarif for SARIF

Check ls -la ISSUES.md REVIEW.md oy.sarif in the workspace root. Custom paths must not escape via ../ or symlinks.

9. oy setup or oy doctor --install-missing fails on tokei/ctags

These are optional context helpers — audits and reviews work without them. They help the oy persona explore large unfamiliar codebases faster.

Retry:

oy doctor --install-missing

They install prebuilt binaries via mise (tokei 12.1.2, ctags nightly release archives) — no Rust toolchain needed. If it still fails, ignore it or install manually.

Still stuck?

oy doctor --json > /tmp/oy-doctor.json   # redact paths if sensitive before sharing
cat /tmp/oy-doctor.json
oy setup --dry-run                       # preview without writing

When asking for help, include:

• oy --version
• agent name and version
• OS and architecture (uname -a)
• install method and scope (global vs workspace)
• redacted oy doctor --json

Do not include credentials, prompts, or sensitive source. See Compatibility.

CLI reference

New user? You probably don’t need this page yet. Most users just talk to their agent: audit this repository with the oy-audit skill — the skill calls these commands for you. Come here when you want exact flags, environment variables, or to automate prepare/finalize outside an agent.

Run oy <command> --help for the exact flags supported by your installed version.

Setup and maintenance

Workflow commands

The oy skills run inside your agent (OpenCode, Cursor, Codex, Copilot, or Gemini CLI). The deterministic evidence steps are CLI commands the skills call:

oy audit prepare options: --path PATH (default .), --out PATH, --format markdown|sarif, --focus TEXT (repeatable), --max-chunks N (default 80). oy review prepare adds an optional positional TARGET branch/commit/ref; omit --path when a target is present.

Ask your agent to “audit this repository” or “review the diff against main”; it loads the matching oy skill, which runs prepare, reads every indexed chunk, writes candidates, and finalizes the report. oy enhance remediation is the oy-enhance skill: ask your agent to fix a finding by ID from ISSUES.md or REVIEW.md.

Unknown oy commands are errors.

Setup ownership and backups

Global setup uses ~/.agents/skills/ (the cross-agent Agent Skills location read natively by OpenCode, Cursor, Codex, Copilot, and Gemini CLI), or OY_SKILLS_DIR when set. Workspace setup uses .agents/skills/ under OY_ROOT. Setup writes:

• oy-audit/SKILL.md, oy-review/SKILL.md, oy-enhance/SKILL.md;
• oy-setup/SKILL.md and oy-setup/oy-persona.md.

Files written by setup carry <!-- Generated by oy setup --> and are oy-owned; setup refreshes them in place and preserves user-modified files without the marker.

Setup also migrates older oy releases: it strips the version-matched @oy-cli/opencode plugin entry, obsolete oy plugin/command/MCP config entries, and direct oy, oy-*, oy.* files under the OpenCode agents/commands/skills/plugins directories from opencode.json(c) and the platform OpenCode config directory. The downloaded OpenCode plugin package cache (<cache>/opencode/packages/@oy-cli/... and the bundled @stablekernel/cursor-opencode-provider fork) is deleted outright; it is a regenerable cache.

Before changing existing owned files, setup creates a mode-0700 backup under the platform state directory (or local-data fallback). Unmodified files remain byte-for-byte untouched. JSON/JSONC comments and formatting are preserved in the backup, while changed configs are pretty-reserialized.

Curl installer

curl -fsSL https://oy.adonm.dev/install.sh | sh                    # prompt for mise scope
curl -fsSL https://oy.adonm.dev/install.sh | sh -s -- --global    # global mise config
curl -fsSL https://oy.adonm.dev/install.sh | sh -s -- --workspace # current mise.toml

The installer uses mise for oy and the optional tokei/Universal Ctags context helpers, then runs oy setup. The default is interactive: choose global config or the current workspace’s mise.toml. Noninteractive installs default to global.

Environment variables

Files written by oy

Report output paths must be workspace-relative and may not escape through parent traversal or symlinks.

Advanced prepare/finalize protocol

The oy skills run these commands automatically:

oy audit prepare [options]
oy audit finalize --run <run-id>
oy review prepare [target] [options]
oy review finalize --run <run-id>

Preparation writes an index, manifest, previous report when present, and ordered chunks under .oy/runs/<run-id>/. Finalization verifies the workspace, evidence hashes, current input, previous output, and candidate report/findings before writing the normalized report.

These commands are public for custom automation. Run their --help output before integrating them.

Path and disclosure boundaries

Input scopes must resolve inside the workspace. The collector’s exclusions and limits are documented in Coverage and limits.

Prepared source may be sent to your configured model provider. oy does not upload reports or store provider credentials. See SECURITY.md.

Compatibility

Which setup do I have?

Not sure? Run:

oy --version
oy doctor --check   # "global skills ok" or "workspace skills ok" means you're good
oy doctor --json | head -n 40

Platforms

The installer requires a POSIX shell plus curl or wget. Its prebuilt oy release supports the three release-archive targets above; other Linux/macOS targets require a source build. Building from source requires Rust 1.96+.

Agent skills hosts

oy does not require any specific agent. The skills are plain Agent Skills (SKILL.md files) under the cross-agent .agents/skills location, which the current releases of OpenCode, Cursor, Codex, GitHub Copilot, and Gemini CLI all discover natively.

If oy doctor --check passes but your agent says “skill not found”, ask it:

run the oy-setup skill

The skill will detect the host and offer to copy the files to the right place. No manual file copying needed.

The optional post-setup OpenCode location refresh uses opencode2 (or OY_OPENCODE). It is best-effort: when OpenCode is absent or unsupported, setup simply skips the refresh and everything else still works.

What doctor --check covers

oy doctor --check

This checks that the canonical skill files are installed with byte-exact content in the global or workspace skills directory and that the obsolete OpenCode plugin package cache is gone. It does not validate your agent’s permission choices or make a model request.

If it fails, run oy setup again and retry. See Troubleshooting for common fixes.

Setup locations

• Global skills: ~/.agents/skills/, or OY_SKILLS_DIR when set
• Workspace skills: OY_ROOT/.agents/skills/
• Legacy OpenCode config cleaned by setup: OPENCODE_CONFIG_DIR, or the platform OpenCode config directory

Setup preserves unrelated configuration and backs up changed oy-owned entries. See Setup ownership and backups.

Optional tools

tokei and Universal Ctags are optional context helpers the oy persona mentions for large unfamiliar scopes. Missing them does not block setup, audit, review, or remediation. Install them with:

oy doctor --install-missing

The helper installs prebuilt artifacts only: tokei 12.1.2 through mise’s Aqua backend and Universal Ctags release archives from the official nightly-build repository.

If the install fails, you can safely ignore it — your first audit will still work.

Reporting a compatibility problem

Include:

• oy --version;
• your agent and its version;
• operating system and architecture;
• install method and setup scope;
• reviewed and redacted oy doctor --json output.

Do not include credentials, prompts, or sensitive source text.

Project direction

oy gives coding agents repeatable audit → review → fix workflows through portable Agent Skills. Any agent that reads .agents/skills can run them; oy itself is not a second agent or model runtime.

Mission

Make repository review in coding agents visible and durable:

prepare known input
  → the agent analyzes it under the user's permissions
  → oy validates a report
  → fix one finding and rerun

Product boundary

Principles

1. Do not add a parallel permission policy. The skills run under whatever permissions the user’s agent has; they never broaden them.
2. Inputs can be repeatable; conclusions cannot. Evidence and report normalization are deterministic, model reasoning is not.
3. Fail instead of silently sampling. Changed evidence, malformed reports, and explicit limits are visible errors.
4. Reports are handoff artifacts. Stable IDs and reruns matter more than chat-only output.
5. Keep host coupling narrow. The only agent-specific code is the optional OpenCode location refresh after setup.
6. Keep one useful persona. The oy persona emphasizes inspection, small changes, verification, and worktree safety without defining permissions.

Current product

Setup writes:

• oy-audit, oy-review, and oy-enhance skills;
• the oy-setup skill and the oy-persona.md it installs into the agent’s environment (improving the default agent or creating an oy agent).

The Rust CLI prepares evidence, verifies model-written candidates, normalizes finding metadata, writes Markdown/SARIF, installs the skills, and migrates legacy OpenCode plugin state.

Non-goals

• becoming a second coding-agent or model runtime;
• owning provider credentials or model routing;
• adding permission overrides;
• adding general shell, edit, web, clone, or search tools;
• claiming deterministic security or quality conclusions;
• running paid model evaluations in default CI.

See Architecture for implementation boundaries and ROADMAP.md for current work.

Architecture

oy is a small evidence and workflow integration for agent skills. The user’s agent (OpenCode, Cursor, Codex, Copilot, or Gemini CLI) owns model execution, providers, permissions, and tools. oy owns deterministic evidence preparation, report finalization, skill installation, and setup glue.

Workflow flow

the agent loads an oy skill (oy-audit, oy-review, or oy-enhance)
  → Rust writes bounded evidence under .oy/runs/<run-id>/
  → the agent reads the index, previous report when present, and every indexed chunk
  → the agent writes candidate report + findings JSON
  → Rust verifies the exact prepared run
  → Rust writes ISSUES.md, REVIEW.md, or SARIF

The skill bodies carry the full protocol; the CLI commands prepare and finalize deterministically.

Main modules

The canonical skill assets are plain Markdown embedded in the binary and written by setup:

Setup

Global setup writes the skills under ~/.agents/skills/ (or OY_SKILLS_DIR), the cross-agent location read natively by OpenCode, Cursor, Codex, Copilot, and Gemini CLI. Workspace setup writes them under OY_ROOT/.agents/skills/. Skill files carry a generated marker and are refreshed in place; user files without the marker are preserved.

Setup also migrates older oy releases: it strips the version-matched @oy-cli/opencode plugin entry and other legacy oy entries from opencode.json(c), moves direct oy-namespaced files out of the OpenCode config directory, and deletes the downloaded OpenCode plugin package cache (a regenerable cache).

When existing config or oy-owned files will change, setup first creates a persistent mode-0700 backup in the platform state location, falling back to the local-data directory when no dedicated state directory exists. Unmodified files remain byte-for-byte untouched. Config writes are a staged rollback-capable batch; if the batch fails, moved files are restored.

After a change, setup asks a running OpenCode 2 service to evict its cached location so the next session discovers the new files; other agents pick the files up on their own discovery cycle.

Artifact verification

Preparation writes model-readable artifacts inside .oy/runs/<run-id>/ and authoritative state in the platform state location, falling back to the local-data directory when needed. The index contains relative artifact paths, coverage metadata, counts, and evidence digest; it does not contain the private authoritative state.

Finalization rejects a mismatched workspace, changed repository evidence, modified immutable artifacts, concurrent output changes, or malformed candidate findings. It can verify artifact integrity and report shape, but it cannot prove that the model read the index, previous report, and every indexed chunk; complete ordered reading is enforced by the skill protocol.

Trust boundaries

Design rules

• Do not add permission overrides; the skills run under whatever permissions the user’s agent has.
• Keep oy to three workflow skills plus the setup skill and persona.
• Put evidence identity, ordering, limits, and report validation in Rust.
• Prefer file artifacts and native agent reads over large tool responses.
• Validate workspace paths at read/write boundaries.
• Do not reintroduce a model client, provider router, chat UI, or general tool registry.