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 "summarize this repo"
oy audit                                     # write an audit report to ISSUES.md
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 -- "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 "explain the project layout"
oy "inspect src/main.rs and suggest a simpler design"
oy "fix the failing tests"
oy audit "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 "summarize this repo"

Model setup

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

OpenAI or OpenAI-compatible

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://your-endpoint.example/v1  # optional
oy model                 # lists models from GET /models when OPENAI_API_KEY is set
oy model <model-from-list>

GitHub Copilot

gh auth login
oy model                 # lists models from Copilot-compatible GET /models when GitHub auth is available
oy model copilot::<model-from-list>

AWS Bedrock

aws configure sso        # one-time setup, or use normal AWS env credentials
export AWS_PROFILE=my-sso
export AWS_REGION=ap-southeast-2
oy model                 # Bedrock-compatible HTTP shims list from GET /models when bearer auth is available
oy model bedrock::<model-id>

Local OpenAI-compatible server

oy model                 # lists models from http://127.0.0.1:8080/v1/models using LOCAL_API_KEY or default local auth
oy model local-8080::<model-from-list>
oy chat

oy model only shows models returned by configured auth-backed OpenAI-compatible /models endpoints. If an opencode or opencode-go key is available, both https://opencode.ai/zen/v1/models and https://opencode.ai/zen/go/v1/models are probed. If no provider auth is available, no selectable models are shown.

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 all endpoints 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.

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 follows redirects by default; it sends an honest oy-cli/<version> user agent plus doc-friendly Accept headers, while still blocking private/local targets and sensitive headers

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.

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 "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 test --locked
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked
cargo run --locked -- --help

License

Apache License 2.0