yoetz（yoetz 搜索）

Yoetz Skill

Fast, agent-friendly LLM council tool for multi-model consensus, code review, and bundling.

When to Use

Explicit triggers only:

• "yoetz ask" / "yoetz council" / "yoetz review"
• "yoetz bundle" / "yoetz generate" / "yoetz browser"
• "use yoetz to..."

NOT triggered by:

• "second opinion" / "ask another model" (could be amq-cli)
• "council" alone / "review" alone (other skills may apply)

Installation (auto-bootstrap)

Before running any yoetz command, ensure the CLI is installed. If command -v yoetz fails, install via one of the following:

Prefer Homebrew when available — pre-built binaries, fastest install.

Agent Contract

• Always use --format json for parsing
• Set YOETZ_AGENT=1 environment variable
• Parse JSON results and present summary to user
• For large bundles, run yoetz bundle first to inspect size
• NEVER type a model ID from memory. Your training data model names are WRONG. Always resolve first.

Model Resolution Protocol (MANDATORY)

NEVER type a model ID from memory. Agent training data contains stale model names. Always query the live registry.

To find the current frontier model per provider:

yoetz models frontier --format json

To find a specific model:

yoetz models resolve "grok" --format json

Use the returned ID verbatim in your commands. Do not modify, shorten, or guess model IDs.

If the registry is stale or empty, sync first:

yoetz models sync

Search for models by keyword:

yoetz models list -s claude --format json

Quick Reference

Replace MODEL_ID with IDs from yoetz models frontier or yoetz models resolve.

Council (Multi-Model Consensus)

Get opinions from multiple LLMs in parallel. --models is required.

yoetz council \
  -p "Should we use async traits or callbacks for this API?" \
  -f src/lib.rs -f src/api/*.rs \
  --models openai/gpt-5.4,gemini/gemini-3.1-pro-preview,openrouter/xai/grok-4.20-multi-agent-beta \
  --format json

Example council sets (illustrative — always resolve live IDs via yoetz models frontier):

• Cross-provider: openai/<FRONTIER>,gemini/<FRONTIER>,openrouter/xai/<FRONTIER>
• Via OpenRouter only: openrouter/openai/<FRONTIER>,openrouter/anthropic/<FRONTIER>,openrouter/google/<FRONTIER>

Ask (Single Model)

Quick question with file context:

yoetz ask \
  -p "What's the bug in this error handling?" \
  -f src/error.rs \
  --provider openai --model gpt-5.4 \
  --format json

For Anthropic/XAI models, use OpenRouter (no extra config needed):

yoetz ask -p "Review this" -f src/*.rs \
  --provider openrouter --model anthropic/claude-sonnet-4.6 \
  --format json

Review

Staged changes

yoetz review diff --staged --format json

Specific file

yoetz review file --path src/main.rs --format json

With custom model

yoetz review diff --staged --provider openai --model gpt-5.4 --format json

Bundle (for manual paste or browser mode)

Bundle creates a session with files at ~/.yoetz/sessions/<id>/bundle.md.

# Get bundle path from JSON output
yoetz bundle -p "Explain this" -f src/**/*.rs --format json
# Output includes: {"artifacts":{"bundle_md":"/Users/.../.yoetz/sessions/.../bundle.md",...},...}

# Extract bundle_md path directly
BUNDLE=$(yoetz bundle -p "Review" -f src/*.rs --format json | jq -r .artifacts.bundle_md)
cat "$BUNDLE"

For browser workflows, pass the bundle.md path:

BUNDLE=$(yoetz bundle -p "Review" -f src/*.rs --format json | jq -r .artifacts.bundle_md)
yoetz browser recipe --recipe chatgpt --bundle "$BUNDLE"

Browser Mode

For web-only models like ChatGPT Pro that lack API access. Connects to your running Chrome via CDP (Chrome DevTools Protocol) to submit bundles through the web UI.

Prerequisites

# Optional fallback browser transports:
npm install -g dev-browser

# Secondary fallback transport:
npm install -g agent-browser

How connection works

yoetz connects to your already logged-in Chrome session via auto-connect (CDP). No cookie extraction or separate browser needed.

Transport priority: chrome-devtools-mcp > dev-browser > agent-browser > manual browser upload.

Connection priority: explicit --cdp > auto-connect > cookie state > profile fallback.

Use --cdp http://127.0.0.1:9222 when you need to target a specific Chrome instance/profile.

First-time setup

Step 1: Enable remote debugging in Chrome

1. Open Chrome and go to chrome://inspect/#remote-debugging
2. Ensure "Discover network targets" is enabled

If Chrome lands on chrome://inspect/#devices instead, that's fine. Keep "Discover network targets" enabled there.

Step 2: Run a recipe

BUNDLE=$(yoetz bundle -p "Review" -f src/*.rs --format json | jq -r .artifacts.bundle_md)
yoetz browser recipe --recipe chatgpt --bundle "$BUNDLE"

Step 3: Approve remote debugging (Chrome 146+) Chrome 146+ may show an "Allow remote debugging?" dialog on the first live attach. Click Allow once for that browser instance.

Step 4: Verify connection

yoetz browser attach

Chrome 146+ notes

Chrome 146 introduced a security dialog for external CDP connections. Yoetz is extension-free by design, so the only way to get "approve once, then run silently" behavior is to keep the daemon/CDP session alive and avoid tearing it down between invocations.

Current policy:

• Prefer live attach over cookie sync: chrome-devtools-mcp first, dev-browser second, agent-browser third.
• Trust an existing live-attach daemon by default; yoetz does not silently recycle it during normal attach/check/recipe flows.
• If recovery is actually needed, use yoetz browser reset explicitly.

If you see "Allow remote debugging?" in Chrome, click Allow and retry.

Explicit --cdp is already supported on yoetz browser attach, check, recipe, and login, but it only bypasses auto-discovery. It does not bypass Chrome's approval gate when targeting the same live browser instance started from chrome://inspect.

If the approval dialog is frozen or unclickable, use the manual CDP path instead:

chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
yoetz browser attach --cdp http://127.0.0.1:9222

Chrome for Testing is also a good fallback for this manual path.

Cookie sync (legacy fallback)

If auto-connect isn't available, cookie sync is still supported:

# Log into ChatGPT in real Chrome, close Chrome, then:
yoetz browser sync-cookies
yoetz browser check

Requires Node >= 24.4. If macOS shows a Keychain prompt for Chrome Safe Storage, click Always Allow.

Use ChatGPT Pro via recipe

# Create bundle and get bundle.md path
BUNDLE=$(yoetz bundle -p "Review this code" -f src/*.rs --format json | jq -r .artifacts.bundle_md)

# Send to ChatGPT
yoetz browser recipe --recipe chatgpt --bundle "$BUNDLE"

# Override the built-in model selection if needed
yoetz browser recipe --recipe chatgpt --bundle "$BUNDLE" --var model=gpt-5-4-pro

# Reuse the currently active ChatGPT tab/conversation for a follow-up turn
# instead of opening a fresh one (default is "fresh" — a fresh conversation
# per call; whether that is a new tab or same-tab navigation depends on the
# transport/session state). Requires the attached tab to already be on chatgpt.com.
yoetz browser recipe --recipe chatgpt --bundle "$BUNDLE" --var thread=reuse

The wait loop reports completion_reason in its JSON output:

• copy_button — the strong signal: a copy control rendered on the new assistant message (response is fully streamed).
• stable_idle_fallback — the page looked idle with unchanged length for ≥ max(90s, 3 × wait_interval_ms). Used when ChatGPT changes its copy-button selectors; otherwise copy_button is the normal completion path.

Combined workflow: API + Browser

# Get fast API results first
yoetz council -p "Review" -f src/*.rs \
  --models openai/gpt-5.4,gemini/gemini-3.1-pro-preview --format json > api.json

# Then get ChatGPT Pro opinion
BUNDLE=$(yoetz bundle -p "Review" -f src/*.rs --format json | jq -r .artifacts.bundle_md)
yoetz browser recipe --recipe chatgpt --bundle "$BUNDLE"

Recipe name resolution

Recipes can be specified by name (resolved from installed locations) or by path:

# By name (searches Homebrew share, XDG, etc.)
yoetz browser recipe --recipe chatgpt --bundle "$BUNDLE"

# By explicit path
yoetz browser recipe --recipe ./my-recipes/custom.yaml --bundle "$BUNDLE"

Built-in recipes: chatgpt, claude, gemini.

Troubleshooting

dev-browser Fallback

When yoetz browser recipe needs manual browser automation, use dev-browser directly against the authenticated Chrome session:

1. Create bundle: BUNDLE=$(yoetz bundle -p "Review" -f src/**/*.ts --format json | jq -r.artifacts.bundle_md)
2. Connect to Chrome: dev-browser --connect <<'EOF' const page = await browser.getPage("chatgpt"); await page.goto("https://chatgpt.com/"); console.log(await page.title()); EOF
3. Use the Playwright-style API: browser.getPage(name), page.goto(url), page.click(selector), page.fill(selector, text), page.evaluate(fn), page.title()
4. Use file helpers when needed: saveScreenshot(buf, name), writeFile(name, data), readFile(name)
5. Target a specific Chrome profile: prefer opening ChatGPT in that profile first, or connect to its explicit CDP endpoint with yoetz browser recipe --cdp http://127.0.0.1:9222...

This keeps the default path aligned with the same browser transport users already rely on outside Yoetz.

How it works

The browser module connects to your running Chrome via CDP (Chrome DevTools Protocol):

• chrome-devtools-mcp (primary): built into yoetz, backed by headless_chrome, attaches directly to your logged-in Chrome session
• dev-browser (fallback): Playwright-based transport for the same live-attach flow
• agent-browser (fallback 2): browser automation fallback with cookie/profile fallback support
• Cookie sync (final fallback): extracts cookies from Chrome's encrypted store, injects into agent-browser only after live attach paths are exhausted
• Extension-free by design: no browser extension is required or desired
• Daemon model: one persistent connection per session, reused across invocations until you explicitly run yoetz browser reset

Provider Configuration

Built-in providers (work with just env var):

• openai - OPENAI_API_KEY
• gemini - GEMINI_API_KEY
• openrouter - OPENROUTER_API_KEY

Via OpenRouter (recommended for Anthropic/XAI - no extra config):

• openrouter/anthropic/claude-sonnet-4.6
• openrouter/xai/grok-4.20-multi-agent-beta

Model format: provider/model

• openai/gpt-5.4
• gemini/gemini-3.1-pro-preview
• openrouter/anthropic/claude-sonnet-4.6 (nested for OpenRouter)

Cost Control

# Estimate before running
yoetz pricing estimate --model gpt-5.4 --input-tokens 12000 --output-tokens 800

# Set limits
yoetz ask -p "Review" --max-cost-usd 1.00 --daily-budget-usd 5.00 --format json

Tips

• Use --debug to capture raw responses during troubleshooting
• Gemini may return empty content if --max-output-tokens is too low
• Session artifacts stored in ~/.yoetz/sessions/<id>/
• For image inputs: yoetz ask -p "Describe" --image photo.png --format json
• ChatGPT recipe placeholder may vary by locale; check snapshot output if fill fails