oy

oy is a local AI coding CLI for your shell. It helps you inspect a codebase, ask questions, make small edits, run commands, and audit repositories from the current workspace.

Quick start

mise use cargo-binstall cargo:oy-cli # install oy with mise
oy doctor                                    # check setup
oy model                                     # choose or confirm a model
oy run "summarize this repo"
oy audit                                     # write an audit report to ISSUES.md
oy enhance                                  # audit, review, then fix selected findings
oy chat                                      # start an interactive session

For an untrusted repository, start read-only:

oy chat --mode plan

Install

Recommended:

mise use cargo-binstall cargo:oy-cli
oy --help

With Cargo:

cargo install oy-cli
oy --help

When developing without installing, replace oy with cargo run --:

cargo run -- run "summarize this repo"
cargo run -- chat

What you need

• bash
• a model provider credential, or a local OpenAI-compatible server
• Rust only if building from source

Start with:

oy doctor
oy model

These commands show what is configured and what to do next.

Common commands

Examples

oy run "explain the project layout"
oy run "inspect src/main.rs and suggest a simpler design"
oy run "fix the failing tests"
oy audit "security and complexity"
oy review main --focus "types and boundaries"
oy enhance --review-target main "security and complexity"
oy run --out docs/plan.md "write a migration plan"
echo "update the changelog" | OY_NON_INTERACTIVE=1 oy run

Use a different workspace:

OY_ROOT=../my-project oy run "summarize this repo"

Model setup

oy supports several model backends. The easiest path is to run oy doctor, then oy model.

Model metadata and selection

If you don't have a model provider yet, OpenCode Go is a decent starting subscription for open-weight models — it provides access to DeepSeek V4, Qwen, Kimi, GLM, and others for $10/month. Install and configure OpenCode, subscribe to Go, then oy will pick up the credentials automatically.

oy model uses opencode models --verbose as the model metadata source. That keeps provider/model listings in OpenCode; oy only keeps the small route/profile metadata needed by its Rust-native backend. Install and configure OpenCode credentials for the providers you want listed, then run:

oy model                 # list currently routable models from opencode models --verbose
oy model <provider/model-from-list>

OpenAI can also be used directly without OpenCode metadata:

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://your-endpoint.example/v1  # optional
oy model openai/gpt-4.1

Provider setup is intentionally OpenCode-shaped: use OpenCode's provider docs and model/provider config docs for credentials, provider options, route defaults, cache behavior, and streamed event shapes. The Rust-native backend tracks OpenCode's LLM provider/protocol package; oy documents only local differences here:

• oy model reads model metadata from opencode models --verbose; OpenCode remains the source of provider/model listings.
• Copilot routes require a Copilot API token (GITHUB_COPILOT_API_KEY or COPILOT_API_KEY), not a GitHub access token.
• Direct OpenAI works without OpenCode metadata via OPENAI_API_KEY; provider options still use OpenCode's shapes.
• Extra oy env aliases beyond OpenCode: GEMINI_API_KEY/GOOGLE_API_KEY, GOOGLE_PROVIDER_OPTIONS, OPENROUTER_BASE_URL, XAI_BASE_URL/XAI_PROVIDER_OPTIONS, AZURE_BASE_URL, BEDROCK_BASE_URL/AWS_BEDROCK_BASE_URL, and CLOUDFLARE_AI_GATEWAY_PROVIDER_API_KEY for Cloudflare AI Gateway downstream bearer auth.

The last five saved model selections are kept as a local quick history. When two or more recent models exist, interactive oy model and /model show that recent list first, with options to inspect the full OpenCode listing or clear the recent history.

Audit

oy audit [focus] creates a deterministic, no-tools repository audit. By default it writes ISSUES.md.

oy audit
oy audit "security and complexity"
oy audit "auth paths" --out docs/audit.md
oy audit --max-chunks 240

The model does not get file-edit tools, shell access, or live search during an audit. The runner collects the review input first, then asks the model to report evidence-first findings. Large repositories fail closed above 80 review chunks by default; pass --max-chunks N when you intentionally want a larger audit.

Review

oy review [target] runs a strict no-tools maintainability review focused on structural simplification, code-judo opportunities, spaghetti branching, abstraction/type boundaries, and 1000-line decomposition risks. With a target, it reviews git diff <target> -- against the current workspace; without one, it reviews the whole workspace. By default it writes REVIEW.md.

oy review
oy review main
oy review HEAD~1 --focus "types and boundaries"
oy review main --out docs/review.md --max-chunks 120

Enhance

oy enhance [focus] runs oy audit, then oy review, shows the combined findings, and addresses the selected items one at a time. Each successful fix is committed before the next finding starts. The command requires a clean git workspace so each commit stays scoped to one finding.

oy enhance
oy enhance --review-target main "security and complexity"
oy enhance --mode auto

By default, enhance prompts you to choose findings. oy enhance --mode auto addresses as many findings as it can unattended, still one finding and one commit at a time. Progress is saved in .tmp/oy-enhance/state.json; rerunning oy enhance resumes any partial run found there, or reparses leftover .tmp/oy-enhance/audit.md / review.md reports if interrupted before state was written. The temporary state is removed after all selected findings are processed.

Interactive chat

In oy chat:

• Enter sends
• Alt+Enter or Shift+Enter inserts a newline
• pasted multiline text stays editable before submit
• /help lists commands
• /status shows model, workspace, mode, context, and todos
• /ask <question> is read-only research; it cannot edit files or run bash
• webfetch can fetch public docs/API pages and return markdown, text, HTML, or XML using the Spider MCP scrape shape; this build uses Spider's default HTTP crawler setup without Chrome/wait/proxy support

For multi-step work, oy keeps an in-memory todo list. It writes TODO.md only when you explicitly ask and the current mode allows it.

The native tool loop treats tool results as a recovery boundary: failures are returned to the model with TOOL_ERROR/RECOVERY guidance, unknown tool names include enabled-tool hints, repeated identical failed calls are blocked, hosted/provider-executed tool events are not dispatched locally, and oversized model-visible tool output is truncated with head/tail preservation.

Safety modes

oy is not a sandbox. It can run commands and edit files with your user permissions. Command output, file snippets, and prompts may be sent to your model provider.

Use safer modes when you are unsure:

Avoid auto-approve unless you trust the workspace, task, and model. For untrusted code, prefer a container or VM and start with oy chat --mode plan.

Sessions and local files

Resume previous work:

oy chat --continue-session
oy run --continue-session "next task"
oy run --resume <name-or-number> "next task"

Default local paths:

Useful environment variables

Troubleshooting

• No model configured: run oy doctor, then oy model.
• Provider call failed: check credentials, selected model, and network/local server access.
• Tool denied: switch mode only if the workspace is trusted, for example oy chat --mode accept-edits.
• Untrusted repo: use oy chat --mode plan first.
• Long task stopped early: increase OY_MAX_TOOL_ROUNDS, for example OY_MAX_TOOL_ROUNDS=2048 oy run "finish the migration".

Development

Maintainer docs:

• CONTRIBUTING.md — local checks, design rules, and release-note expectations.
• docs/architecture.md — runtime flow, module map, trust boundaries, and audit pipeline.
• docs/tool-safety.md — tool capabilities, approval modes, and boundary guidance.

Top-level source layout:

Checks:

cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo nextest run --all-targets --locked --profile ci
cargo test --doc --locked
cargo +nightly miri test --locked miri_smoke
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked
cargo run --locked -- --help

License

Apache License 2.0