oy

Repeatable repository audits and reviews for opencode.

oy is for maintainers who already use opencode and want a bounded, reviewable workflow for repository-wide security audits, code-quality reviews, and finding remediation.

opencode still owns the model, provider, UI, sessions, permissions, edits, shell, and web tools. oy adds:

• deterministic, gitignore-aware repository and diff collection,
• restricted audit/review agents that cannot use generic shell, edit, or search tools,
• Markdown and SARIF rendering with stable finding IDs and statuses,
• a one-finding-at-a-time remediation handoff.

The inputs, ordering, limits, and report rendering are deterministic. Model conclusions are not; model choice and prompt quality still affect findings.

Quick start

Requirements: opencode with a configured provider, plus git for diff reviews.

curl -fsSL https://adonm.github.io/oy-cli/install.sh | sh
# Restart or activate your shell as the installer prints, then:
oy doctor
oy audit

The installer uses mise to install or upgrade oy, opencode, tokei, and Universal Ctags, then writes the global opencode integration with oy setup. Source-built Sighthound is opt-in with OY_INSTALL_SIGHTHOUND=1 and requires Rust 1.85+.

For a minimal manual install:

mise use --global cargo-binstall cargo:oy-cli opencode
oy setup
oy doctor

Configure authentication and models with opencode's provider guide. See the getting-started guide for install behavior, supported release targets, and workspace-local setup.

Core workflow

1. Audit a repository

oy audit
oy audit "authentication and authorization"
oy audit src/auth
oy audit --format sarif --out oy.sarif

The default report is ISSUES.md. An exact workspace-relative path narrows collection; other text is an audit lens. SARIF output can be consumed by code-scanning tools.

2. Review a workspace or target diff

oy review
oy review main
oy review main --focus "types and trust boundaries"

With no target, oy reviews the collected workspace. With a branch, commit, or ref, it reviews deterministic git diff <target> input. The default report is REVIEW.md.

3. Fix one finding

oy enhance <finding-id>

Reports include stable IDs and statuses. oy enhance selects one actionable finding, makes a focused change through opencode's permission system, and verifies it when possible. Rerunning an audit or review reads the previous generated report once and carries forward only findings that remain current.

See the workflow guide for report semantics, scope behavior, failure limits, and practical examples.

Why not just prompt opencode?

A free-form agent can choose what to inspect and may silently sample a large repository. The oy audit/review protocol instead:

1. inventories the requested scope,
2. creates ordered chunks or target-diff chunks,
3. fails closed when the configured chunk budget is exceeded,
4. requires the restricted agent to read every collected chunk,
5. normalizes the final report for reruns and remediation.

This makes coverage decisions visible and repeatable without rebuilding opencode's general coding agent.

Coverage boundary

“Every chunk” means every chunk produced by oy's collector, not every byte in the repository. Collection skips gitignored and hidden paths, common dependency/build directories, lockfiles, likely-secret files, generated reports, binary/non-UTF-8/empty files, unreadable files, and files larger than 512 KiB. Review these exclusions before treating an audit as complete for a high-assurance use case.

Sighthound uses independent gitignore-aware discovery and its own filters/size limit. It may inspect supported hidden source or source files larger than oy's 512 KiB collector limit. The auditor calls it only when the focus explicitly requests Sighthound or SAST; returned snippets may be sent to the model provider.

Optional local evidence tools add:

Install them with:

mise use --global cargo:tokei
mise use --global github:universal-ctags/ctags
mise use --global cargo:https://github.com/Corgea/Sighthound@tag:1.0

Sighthound 1.0 is built from source and requires Rust 1.85+. It scans Python, JavaScript/TypeScript, Java, PHP, C#, Go, Ruby, HTML, and Django templates; it does not scan Rust or C/C++. OY_TOKEI, OY_CTAGS, and OY_SIGHTHOUND can select absolute helper paths. Automatic discovery rejects relative PATH entries.

Setup and launcher behavior

oy setup writes ~/.config/opencode/opencode.json plus generated agents and skills. Use oy setup --workspace for .opencode/ integration or oy setup --dry-run to preview changes.

Launch-oriented commands (oy, open, run, chat, model, audit, review, and enhance) refresh the global integration before starting opencode and refresh an existing workspace integration when detected. The config merge owns mcp.oy, command.oy-*, and tool_output.max_bytes/max_lines. Other object keys are retained, but the JSON/JSONC file is pretty-serialized, so comments and formatting are not preserved. Generated Markdown files refuse to replace files without oy's generated marker.

oy with no subcommand launches the general oy coding agent. run, chat, model, safety modes, and unknown-command passthrough remain compatibility conveniences; audit, review, and remediation are the project's primary direction.

Command map

The full CLI and MCP inventory are in the reference.

Safety

oy is not a sandbox. Repository text returned by MCP may be sent to the model provider selected in opencode. Native oy can read collected workspace text, run fixed read-only helper processes, write requested reports inside the workspace, update integration config, and launch opencode. General edits, shell, web, and provider traffic remain governed by opencode.

Use restrictive opencode permissions and a disposable environment for untrusted repositories. Read SECURITY.md and the tool safety notes before high-risk use.

Project direction and development

The product contract is intentionally narrow: improve the audit → review → remediate loop without becoming another model client or general agent framework. See ROADMAP.md for current outcomes and explicit non-goals.

just dev
just check
just eval
just docs

Contributor references: architecture, evaluation, contributing, and docs.rs API.