synu

A universal wrapper for AI agents that tracks quota usage for Synthetic API calls.

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/amolith/llm-projects'
fundle init

Then reload your shell or 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 claude (auto-configured for Synthetic)
synu claude "What does functions/synu.fish do?"

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

# Any other agent or command
synu [agent-name] [agent-args...]

Claude Code Configuration

When using Claude Code through synu, the following models are configured by default:

Override Models with 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

Interactive Model Selection

Use synu i <agent> to interactively select models using gum:

synu i claude "prompt"

This will present a TUI to choose between group or individual model selection, then let you filter and select from available Synthetic models.

How it works

synu works by:

1. Loading agent-specific configuration if available (e.g., Claude Code model defaults)
2. Fetching initial quota from the Synthetic API before running the agent
3. Executing the specified agent with all provided arguments
4. Fetching final quota after the agent completes
5. Calculating and displaying session usage

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

Adding Support for New Agents

Agent definitions are stored in functions/_synu_agents/. Each agent file can define:

• _synu_agent_<name>_flags - Returns argparse flag specification
• _synu_agent_<name>_configure - Sets environment variables before execution
• _synu_agent_<name>_interactive - Implements interactive model selection

Agents without definitions work as passthrough with quota tracking.

Shell completions

Synu includes fish shell completions for better usability.

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.