From 998730f48696784333c820a9f9ea1e04158115cc Mon Sep 17 00:00:00 2001 From: Amolith Date: Wed, 3 Dec 2025 18:09:31 -0700 Subject: [PATCH] docs(readme): clarify agent invocation patterns Show correct interactive vs non-interactive usage for each agent. Add install commands and fix table formatting. Assisted-by: Claude Sonnet 4 via Crush --- README.md | 110 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 76 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index b12e5c53a2ea166f2b18f4fec4844554d856556a..84ea81716d6b761cc0e88b4ffdfe721fbe65e5b8 100644 --- a/README.md +++ b/README.md @@ -88,13 +88,20 @@ Use `synu` as a wrapper for any AI agent: # Check current quota synu -# Use with configured agents (auto-routed through Synthetic) -synu claude "What does functions/synu.fish do?" -synu opencode "Help me refactor this" -synu aider "Fix the bug in main.go" +# Start an agent's interactive TUI (most common usage) +synu claude +synu opencode +synu aider -# Use with other agents (passthrough with quota tracking) -synu crush "Help me write code" +# Non-interactive / one-shot mode (agent-specific flags) +synu claude -p "What does functions/synu.fish do?" +synu opencode run "Help me refactor this" +synu aider -m "Fix the bug in main.go" # aider's -m is --message +synu llxprt "prompt" # positional works +synu qwen "prompt" # positional works (one-shot by default) + +# Passthrough agents (quota tracking only) +synu crush run "Help me write code" # Any other agent or command synu [agent-name] [agent-args...] @@ -111,9 +118,13 @@ Use `synu i ` to fetch the list of available models and interactively filter/select them using gum: ```fish -synu i claude "prompt" -synu i opencode "prompt" -synu i aider "prompt" +# Select models interactively, then start agent TUI +synu i claude +synu i opencode +synu i aider + +# Additional agent args are passed through after model selection +synu i claude -p "Non-interactive with selected model" ``` You'll be asked whether to save your selection as the default for future @@ -129,7 +140,9 @@ changed. Command-line flags always override saved preferences. ### Claude Code -| Tier | Default Model | +Install: `curl -fsSL https://claude.ai/install.sh | bash` + +| Slot | Default | | -------- | --------------------------------------- | | Opus | `hf:moonshotai/Kimi-K2-Thinking` | | Sonnet | `hf:zai-org/GLM-4.6` | @@ -139,63 +152,92 @@ changed. Command-line flags always override saved preferences. **Override flags:** ```fish -# Override specific models -synu claude --opus hf:other/model "prompt" -synu claude --sonnet hf:other/model "prompt" -synu claude --haiku hf:other/model "prompt" -synu claude --agent hf:other/model "prompt" +# Override specific models (opens TUI) +synu claude --opus hf:other/model +synu claude --sonnet hf:other/model +synu claude --haiku hf:other/model +synu claude --agent hf:other/model # Group overrides -synu claude --large hf:model "prompt" # Sets Opus, Sonnet, and Subagent -synu claude --light hf:model "prompt" # Sets Haiku +synu claude --large hf:model # Sets Opus, Sonnet, and Subagent +synu claude --light hf:model # Sets Haiku + +# Non-interactive with model override +synu claude --large hf:model -p "What does this code do?" ``` ### OpenCode -| Default Model | -| -------------------- | -| `hf:zai-org/GLM-4.6` | +Install: `bun i -g opencode-ai` + +| Slot | Default | +| ----- | -------------------- | +| Model | `hf:zai-org/GLM-4.6` | ```fish -synu opencode --model hf:other/model "prompt" +# TUI mode with model override +synu opencode --model hf:other/model + +# Non-interactive +synu opencode --model hf:other/model run "Help me refactor this" ``` ### Aider -| Slot | Default Model | +Install: `uv tool install --force --python python3.12 --with pip aider-chat@latest` + +| Slot | Default | | ------ | --------------------------------------- | | Main | `hf:zai-org/GLM-4.6` | | Editor | `hf:deepseek-ai/DeepSeek-V3.1-Terminus` | ```fish -# Single model mode -synu aider --model hf:some/model "prompt" +# Chat mode with model override +synu aider --model hf:some/model -# Architect + editor mode (two models) -synu aider --model hf:architect/model --editor-model hf:editor/model "prompt" +# Non-interactive (one-shot message) +synu aider --model hf:some/model -m "Fix the bug in main.go" + +# Architect + editor mode +synu aider --model hf:architect/model --editor-model hf:editor/model ``` +> **Note**: synu uses `--model` (long form only) for aider to avoid +> collision with aider's `-m` (`--message`) flag. + ### llxprt -| Default Model | -| -------------------- | -| `hf:zai-org/GLM-4.6` | +Install: `bun i -g @vybestack/llxprt-code` + +| Slot | Default | +| ----- | -------------------- | +| Model | `hf:zai-org/GLM-4.6` | > **Note**: llxprt doesn't support setting credentials via environment > variables. Run `/key {your_api_key}` once at the llxprt prompt to configure. ```fish -synu llxprt --model hf:other/model "prompt" +# TUI mode with model override +synu llxprt --model hf:other/model + +# Non-interactive (positional prompt) +synu llxprt --model hf:other/model "Explain this code" ``` ### Qwen Code -| Default Model | -| -------------------- | -| `hf:zai-org/GLM-4.6` | +Install: `bun i -g @qwen-code/qwen-code@latest` + +| Slot | Default | +| ----- | -------------------- | +| Model | `hf:zai-org/GLM-4.6` | ```fish -synu qwen --model hf:other/model "prompt" +# One-shot mode with model override (positional prompt) +synu qwen --model hf:other/model "Explain this code" + +# Interactive mode +synu qwen --model hf:other/model -i "Start from this prompt" ``` ## How it works