1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: Unlicense
  5-->
  6
  7# synu
  8
  9A universal wrapper for AI agents that tracks quota usage for [Synthetic](https://synthetic.new) API calls.
 10
 11## Requirements
 12
 13- Fish
 14- `curl` - for API requests
 15- `jq` - for JSON parsing
 16- `gum` - for interactive model selection ([install](https://github.com/charmbracelet/gum))
 17- `SYNTHETIC_API_KEY` environment variable (for quota tracking with Synthetic)
 18
 19## Installation
 20
 21### Using Fundle
 22
 23Add to your `~/.config/fish/config.fish`:
 24
 25```fish
 26fundle plugin 'synu' --url 'https://git.secluded.site/amolith/llm-projects'
 27fundle init
 28```
 29
 30Then reload your shell or run `fundle install`.
 31
 32## Configuration
 33
 34Set your Synthetic API key in your `~/.config/fish/config.fish`:
 35
 36```fish
 37# For Synthetic API quota tracking
 38set -gx SYNTHETIC_API_KEY your_api_key_here
 39```
 40
 41## Usage
 42
 43Use `synu` as a wrapper for any AI agent:
 44
 45```fish
 46# Check current quota
 47synu
 48
 49# Use with claude (auto-configured for Synthetic)
 50synu claude "What does functions/synu.fish do?"
 51
 52# Use with other agents (passthrough with quota tracking)
 53synu crush "Help me write code"
 54
 55# Any other agent or command
 56synu [agent-name] [agent-args...]
 57```
 58
 59### Claude Code Configuration
 60
 61When using Claude Code through synu, the following models are configured by default:
 62
 63| Tier | Model |
 64|------|-------|
 65| Opus | `hf:moonshotai/Kimi-K2-Thinking` |
 66| Sonnet | `hf:MiniMaxAI/MiniMax-M2` |
 67| Haiku | `hf:deepseek-ai/DeepSeek-V3.1-Terminus` |
 68| Subagent | `hf:MiniMaxAI/MiniMax-M2` |
 69
 70#### Override Models with Flags
 71
 72```fish
 73# Override specific models
 74synu claude --opus hf:other/model "prompt"
 75synu claude --sonnet hf:other/model "prompt"
 76synu claude --haiku hf:other/model "prompt"
 77synu claude --agent hf:other/model "prompt"
 78
 79# Group overrides
 80synu claude --large hf:model "prompt"  # Sets Opus, Sonnet, and Subagent
 81synu claude --light hf:model "prompt"  # Sets Haiku
 82```
 83
 84#### Interactive Model Selection
 85
 86Use `synu i <agent>` to interactively select models using gum:
 87
 88```fish
 89synu i claude "prompt"
 90```
 91
 92This will present a TUI to choose between group or individual model selection, then let you filter and select from available Synthetic models.
 93
 94### How it works
 95
 96`synu` works by:
 97
 981. Loading agent-specific configuration if available (e.g., Claude Code model defaults)
 992. Fetching initial quota from the Synthetic API before running the agent
1003. Executing the specified agent with all provided arguments
1014. Fetching final quota after the agent completes
1025. Calculating and displaying session usage
103
104The quota tracking requires the `SYNTHETIC_API_KEY` environment variable to be set. Without it, `synu` will still work but will show a warning and skip quota tracking.
105
106### Adding Support for New Agents
107
108Agent definitions are stored in `functions/_synu_agents/`. Each agent file can define:
109
110- `_synu_agent_<name>_flags` - Returns argparse flag specification
111- `_synu_agent_<name>_configure` - Sets environment variables before execution
112- `_synu_agent_<name>_interactive` - Implements interactive model selection
113
114Agents without definitions work as passthrough with quota tracking.
115
116## Shell completions
117
118Synu includes fish shell completions for better usability.
119
120## Contributions
121
122Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
123new account to contribute, you don't need to fork this repo, you don't need to
124fiddle with `git send-email`, you don't need to faff with your email client to
125get `git request-pull` working...
126
127You just need:
128
129- Git
130- SSH
131- An SSH key
132
133```sh
134# Clone this repo, make your changes, and commit them
135# Create a new patch request with
136git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
137# After potential feedback, submit a revision to an existing patch request with
138git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
139# List patch requests
140ssh pr.pico.sh pr ls amolith/llm-projects
141```
142
143See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
144complete example workflow.
145
146[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
147[pr.pico.sh]: https://pr.pico.sh