# Getting started
> **New here? TL;DR — 2 minutes:**
> ```bash
> 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](compatibility.md) for tested versions.
## 1. Install oy
### Recommended: one-line installer
```bash
When prompted, choose **Global** unless you only want oy in the current repository.
To skip the prompt (for scripts or CI):
```bash
```
What the installer does:
1. Installs [mise](https://mise.jdx.dev/) (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`](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):**
```bash
mise use --global --yes --minimum-release-age 0 github:adonm/oy-cli@0.15.1
mise exec github:adonm/oy-cli@0.15.1 -- oy setup
```
**From source (requires Rust 1.96+):**
```bash
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:**
```bash
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:
```bash
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:
```text
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)
| **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 `<!-- Generated by oy setup -->`). See [Setup ownership](reference.md#setup-ownership-and-backups).
## 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):**
```text
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):**
```text
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:**
```text
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](workflows.md#coverage-and-limits).
## If something fails — quick fixes
| `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](compatibility.md) 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?
```bash
```
Include `oy --version`, your agent + version, OS/architecture, and redacted `oy doctor --json` when asking for help (see [Compatibility](compatibility.md#reporting-a-compatibility-problem)).
## Next steps
- [Workflow guide](workflows.md) — choose scopes (path vs focus), understand statuses (`new`, `fixed?`, `stale`), and remediation loops
- [Examples and CI](examples.md) — see real `ISSUES.md` / `REVIEW.md` / SARIF snippets and GitHub Actions upload
- [Troubleshooting](troubleshooting.md) — expanded fixes with copy-paste commands
- [CLI reference](reference.md) — every command, environment variable, and file layout