synu

Universal wrapper for LLM agents that tracks Synthetic 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)
• SYNTHETIC_API_KEY environment variable (for quota tracking with Synthetic)

Installation

Using Fundle

Add to your ~/.config/fish/config.fish:

fundle plugin 'synu' --url 'https://git.secluded.site/synu'
fundle init

Then reload your shell and run fundle install.

Configuration

Set your Synthetic API key in your ~/.config/fish/config.fish:

# For Synthetic API quota tracking
set -gx SYNTHETIC_API_KEY your_api_key_here

Usage

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"

# Use with other agents (passthrough with quota tracking)
synu crush "Help me write code"

# Any other agent or command
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.

Interactive Model Selection

Use synu i <agent> to fetch the list of available models and interactively filter/select them using gum:

synu i claude "prompt"
synu i opencode "prompt"
synu i aider "prompt"

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.

Configured Agents

Claude Code

Override flags:

# 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"

# Group overrides
synu claude --large hf:model "prompt"  # Sets Opus, Sonnet, and Subagent
synu claude --light hf:model "prompt"  # Sets Haiku

OpenCode

synu opencode --model hf:other/model "prompt"

Aider

# Single model mode
synu aider --model hf:some/model "prompt"

# Architect + editor mode (two models)
synu aider --model hf:architect/model --editor-model hf:editor/model "prompt"

llxprt

synu llxprt --model hf:other/model "prompt"

Qwen Code

synu qwen --model hf:other/model "prompt"

How it works

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
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.

Shell completions

Synu includes fish shell completions for configured agents and their flags.

Contributions

Patch requests are in amolith/llm-projects on pr.pico.sh. You don't need a new account to contribute, you don't need to fork this repo, you don't need to fiddle with git send-email, you don't need to faff with your email client to get git request-pull working...

You just need:

• Git
• SSH
• An SSH key

# Clone this repo, make your changes, and commit them
# Create a new patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
# After potential feedback, submit a revision to an existing patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
# List patch requests
ssh pr.pico.sh pr ls amolith/llm-projects

See "How do Patch Requests work?" on pr.pico.sh's home page for a more complete example workflow.