yoetz

# yoetz

<p>
  <img src="assets/branding/yoetz-quorum-mark.svg" alt="Yoetz quorum mark" width="96" height="96">
</p>

[![CI](https://github.com/avivsinai/yoetz/actions/workflows/ci.yml/badge.svg)](https://github.com/avivsinai/yoetz/actions/workflows/ci.yml)
[![Latest Release](https://img.shields.io/github/v/release/avivsinai/yoetz)](https://github.com/avivsinai/yoetz/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Rust: 1.88+](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org/)

Fast CLI for routing code and media work through the right LLM path: direct API
calls when available, multi-model councils when you need agreement, and browser
recipes for web-only models such as ChatGPT Pro and Claude's Fable 5.

Yoetz is built for coding agents and terminal workflows: gitignore-aware
bundles, structured JSON output, reproducible session artifacts, live model
resolution, local budget checks, and multimodal inputs across OpenAI,
OpenRouter, Gemini, and LiteLLM-compatible backends.

> Yoetz is under active development. Command behavior may change before 1.0.

## What It Does

- **Bundle** repository context into prompt-ready artifacts without fighting
  `.gitignore`.
- **Ask** one model with text, code, images, or video.
- **Council** multiple models in parallel when you want independent opinions.
- **Review** staged diffs or files with agent-readable output.
- **Generate** images and video through providers that expose generation APIs.
- **Use browser recipes** for web-only model surfaces while keeping terminal
  output parseable.

## Install

### Homebrew

```bash
brew install avivsinai/tap/yoetz
yoetz --version
```

### Scoop

```powershell
scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket
scoop install yoetz
yoetz --version
```

### Prebuilt Binaries

Download archives and checksums from the
[latest GitHub release](https://github.com/avivsinai/yoetz/releases/latest).

```bash
curl -fLO https://github.com/avivsinai/yoetz/releases/latest/download/yoetz-aarch64-apple-darwin.tar.gz
curl -fLO https://github.com/avivsinai/yoetz/releases/latest/download/SHA256SUMS.txt
shasum -a 256 -c SHA256SUMS.txt --ignore-missing
tar xzf yoetz-aarch64-apple-darwin.tar.gz
sudo mv yoetz /usr/local/bin/
```

Release archives are published for macOS, Linux, and Windows targets. Use
`sha256sum` instead of `shasum -a 256` on Linux.

### From Source

```bash
cargo install --git https://github.com/avivsinai/yoetz --locked
```

## Agent Skills

Yoetz also ships an agent skill so Claude Code, Codex CLI, and compatible agent
runtimes know how to call the CLI safely: resolve live model IDs, keep stdout
parseable, bundle large context first, and use browser recipes intentionally.

### Codex / Claude Plugin Marketplace

```text
/plugin marketplace add avivsinai/skills-marketplace
/plugin install yoetz@avivsinai-marketplace
```

### skills.sh

```bash
npx skills add avivsinai/yoetz
```

### skild.sh

```bash
npx skild install @avivsinai/yoetz
```

The skill source lives at [skills/yoetz/SKILL.md](skills/yoetz/SKILL.md) and is
versioned with the CLI release metadata.

## First Run

Start with a command that needs no API key:

```bash
yoetz bundle -p "Summarize this project" -f README.md --format json
```

Then configure at least one provider. Environment variables are enough for most
users:

```bash
export OPENROUTER_API_KEY=...
export OPENAI_API_KEY=...
export GEMINI_API_KEY=...
```

For persistent configuration:

```bash
mkdir -p ~/.config/yoetz
cat > ~/.config/yoetz/config.toml <<'EOF'
[defaults]
provider = "openrouter"
# Optional after resolving a current model ID:
# model = "<id from yoetz models resolve>"

[providers.openrouter]
base_url = "https://openrouter.ai/api/v1"
api_key_env = "OPENROUTER_API_KEY"
kind = "openai-compatible"
EOF
```

From a source checkout, you can start from the full example instead:

```bash
cp docs/config.example.toml ~/.config/yoetz/config.toml
```

Yoetz also supports `YOETZ_CONFIG_PATH`, repo-local `./yoetz.toml`, and profile
overlays selected with `--config-profile <name>`. See
[docs/config.example.toml](docs/config.example.toml) for the shape. Global
`--timeout-secs` controls provider HTTP calls and local Cursor CLI calls, and
defaults to `180`.
`--allow-unknown` permits model IDs that are absent from the registry; reserve
it for self-hosted models whose IDs cannot be registered.

The default `models frontier` lab list is configurable with
`[frontier].families`; `--all` and `--family` continue to bypass that list.

`yoetz ask` writes artifacts to `~/.yoetz/sessions/<id>/` by default. Headless
callers can skip that entirely with `yoetz ask --no-session` (or
`[sessions] no_session = true`), and `[sessions] max_age_days` /
`[sessions] max_count` prune old or excess session dirs on startup. Both are
off by default, and `[sessions]` is only honored from trusted config
locations, never from repo-local `./yoetz.toml`. A `max_c

... (truncated)