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:

Installs mise (if missing) with its official bootstrap for bash/zsh/fish;
Installs a prebuilt oy release with mise;
Installs prebuilt tokei and Universal Ctags context helpers (optional, for large repos);
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)

Scope	Command	When to use
Global (default)	`oy setup`	Your personal workstation — skills available in every repo
Workspace	`oy setup --workspace`	Only this repository should load oy
Preview	`oy setup --dry-run`	See what setup would change without writing
Remove	`oy setup --remove`	Back up and remove oy-owned skills and legacy config

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 ). 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

Symptom	Fix
`oy: command not found`	Restart your shell (mise activation) or add `~/.local/bin` to `PATH`; try `mise exec github:adonm/oy-cli@latest -- oy --version` to test
`oy doctor` says legacy plugin cache present	Run `oy setup` again — it deletes the obsolete cache under `~/.cache/opencode/packages`
`oy doctor --check` says skills missing	Run `oy setup`, then `oy doctor --check`; if it still fails, check `~/.agents/skills/oy-audit/SKILL.md` exists and `OY_SKILLS_DIR` isn’t pointing elsewhere
Agent says “skill not found”	Ask the agent to run the `oy-setup` skill — it will copy/symlink to your agent’s directory (e.g. `.claude/skills`). See Compatibility for each agent’s search path
`exceeds max-chunks 80`	Narrow the scope: `audit src/auth with the oy-audit skill` — only raise `--max-chunks` when the broader scope is intentional
`not a git repository` or bad target	Target-diff reviews need a git repo and a valid ref — try `git rev-parse --verify main` first
Model not responding / auth error	Configure your provider in your agent (Cursor: Settings → Models, OpenCode: `opencode.jsonc`). `oy` never handles API keys
Empty or sparse report	Expected for small/mature repos — check `oy-findings` JSON block is `[]` and verdict says no concerns; try a more focused prompt or different model

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

Keyboard shortcuts

oy documentation