diff --git a/README.md b/README.md index 7dbce070af3dc4cdcb57bca185ff20dc22099c89..b5e47809c6f6ae1791f036034623ded152d8cad4 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,21 @@ SPDX-License-Identifier: Unlicense # synu -A universal wrapper for AI agents that tracks quota usage for [Synthetic](https://synthetic.new) API calls. +Universal wrapper for LLM agents that tracks +[Synthetic](https://synthetic.new) usage and interactively preconfigures +supported agents for currently-available models (so you can try a new +one as soon as they support it, without waiting for the agent itself to +gain support!) ## Requirements - Fish - `curl` - for API requests - `jq` - for JSON parsing -- `gum` - for interactive model selection ([install](https://github.com/charmbracelet/gum)) -- `SYNTHETIC_API_KEY` environment variable (for quota tracking with Synthetic) +- `gum` - for interactive model selection + ([install](https://github.com/charmbracelet/gum)) +- `SYNTHETIC_API_KEY` environment variable (for quota tracking with + Synthetic) ## Installation @@ -23,7 +29,7 @@ A universal wrapper for AI agents that tracks quota usage for [Synthetic](https: Add to your `~/.config/fish/config.fish`: ```fish -fundle plugin 'synu' --url 'https://git.secluded.site/amolith/llm-projects' +fundle plugin 'synu' --url 'https://git.secluded.site/synu' fundle init ``` @@ -58,11 +64,15 @@ synu crush "Help me write code" synu [agent-name] [agent-args...] ``` -> **Note**: synu's configuration is ephemeral and non-invasive. Running `synu claude` routes requests through Synthetic, but running `claude` directly still uses Anthropic's API with your normal configuration. synu never modifies the agent's own config files. +> **Note**: synu's configuration is ephemeral and non-invasive. Running +> `synu claude` routes requests through Synthetic, but running `claude` +> directly still uses Anthropic's API with your normal configuration. +> synu never modifies the agent's own config files. ### Interactive Model Selection -Use `synu i ` to interactively select models using gum: +Use `synu i ` to fetch the list of available models and +interactively filter/select them using gum: ```fish synu i claude "prompt" @@ -70,11 +80,14 @@ synu i opencode "prompt" synu i aider "prompt" ``` -This presents a TUI to filter and select from available Synthetic models. You'll be prompted to save your selection as the default for future sessions. +You'll be asked whether to save your selection as the default for future +sessions. ### Persistent Preferences -Model selections made in interactive mode can be saved to `~/.config/synu/models.conf`. These become the new defaults until changed. Command-line flags always override saved preferences. +Model selections made in interactive mode can be saved to +`~/.config/synu/models.conf`. These become the new defaults until +changed. Command-line flags always override saved preferences. ## Configured Agents @@ -151,27 +164,17 @@ synu qwen --model hf:other/model "prompt" `synu` works by: 1. Loading agent-specific configuration if available -2. Fetching initial quota from the Synthetic API before running the agent -3. Configuring the agent's environment/CLI args to route through Synthetic +2. Fetching initial quota from the Synthetic API before running the + agent +3. Configuring the agent's environment/CLI args to route through + Synthetic 4. Executing the specified agent with all provided arguments 5. Cleaning up environment variables after execution 6. Fetching final quota and displaying session usage -The quota tracking requires the `SYNTHETIC_API_KEY` environment variable. Without it, `synu` will show a warning and skip quota tracking, but still attempt to run the agent. - -### Adding Support for New Agents - -Agent definitions are stored in `functions/_synu_agents/`. Each agent file can define: - -- `_synu_agent__flags` - Returns argparse flag specification -- `_synu_agent__configure` - Sets environment variables/state before execution -- `_synu_agent__args` - Returns CLI arguments to inject -- `_synu_agent__env_vars` - Lists environment variables to clean up -- `_synu_agent__interactive` - Implements interactive model selection - -Agents without definitions work as passthrough with quota tracking. - -See `AGENTS.md` for detailed implementation guidance. +The quota tracking requires the `SYNTHETIC_API_KEY` environment +variable. Without it, `synu` will show a warning and skip quota +tracking, but still attempt to run the agent. ## Shell completions