<!--
SPDX-FileCopyrightText: Amolith <amolith@secluded.site>

SPDX-License-Identifier: Unlicense
-->

# synu

A universal wrapper for AI agents that tracks quota usage for [Synthetic](https://synthetic.new) API calls.

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

## Installation

### Using Fundle

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

```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`:

```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:

```fish
# 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:

| Tier | Model |
|------|-------|
| Opus | `hf:moonshotai/Kimi-K2-Thinking` |
| Sonnet | `hf:MiniMaxAI/MiniMax-M2` |
| Haiku | `hf:deepseek-ai/DeepSeek-V3.1-Terminus` |
| Subagent | `hf:MiniMaxAI/MiniMax-M2` |

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

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

```fish
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

```sh
# 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.

[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
[pr.pico.sh]: https://pr.pico.sh