1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: Unlicense
5-->
6
7# synclaude.fish
8
9[](https://api.reuse.software/info/git.secluded.site/synclaude.fish)
11[](https://liberapay.com/Amolith/)
12
13A Fish wrapper for the `claude` CLI that routes requests through
14[Synthetic.new](https://synthetic.new), enabling use of models like GLM-4.6
15through `claude`.
16
17
18
19## tl;dr
20
21- Configurable defaults per model tier with persistent caching
22- Displays session usage and remaining API quota after each run
23- `synclaude u` shows current quota
24- Invoke as `synclaude i` for an interactive model picker with save-as-default option
25- Configure models by group or individually through the interactive picker or flags
26
27## Requirements
28
29- Fish
30- `claude`
31- [gum](https://github.com/charmbracelet/gum) - for TUI prompts and spinners
32- [jq](https://jqlang.github.io/jq/) - for JSON parsing
33- `curl` - for API requests
34- `SYNTHETIC_API_KEY` environment variable
35
36## Installation
37
38### Using Fundle
39
40Add to your `~/.config/fish/config.fish`:
41
42```fish
43fundle plugin 'synclaude' --url 'https://git.secluded.site/synclaude.fish'
44fundle init
45```
46
47Then reload your shell or run `fundle install`.
48
49## Configuration
50
51Set your Synthetic API key in your `~/.config/fish/config.fish`:
52
53```fish
54set -gx SYNTHETIC_API_KEY your_api_key_here
55```
56
57## Usage
58
59### Check quota
60
61Run with `u` subcommand to see current API usage:
62
63```fish
64synclaude u
65# Usage: 42% (580/1000 remaining)
66```
67
68### Basic
69
70Use `synclaude` exactly like you would use `claude`:
71
72```fish
73# TUI
74synclaude
75
76# Non-interactively
77synclaude -p "What does functions/synclaude.fish do?"
78```
79
80### Default Models
81
82| Tier | Default Model |
83|------|--------------|
84| Opus | `hf:moonshotai/Kimi-K2-Thinking` |
85| Sonnet | `hf:zai-org/GLM-4.6` |
86| Haiku | `hf:deepseek-ai/DeepSeek-V3.1-Terminus` |
87| Sub-agent | `hf:zai-org/GLM-4.6` |
88
89Defaults can be overridden with flags or saved persistently through interactive mode.
90
91### Interactive overrides
92
93Launch the interactive picker with the `i` subcommand:
94
95```fish
96synclaude i
97```
98
991. Select whether to override models by group or by specific model
1002. Select which ones to override
1013. Select what to override them with (shows current defaults in header)
1024. Optionally save selections as new defaults
103
104### Flags
105
106#### Group flags
107
108| Flag | Short | Description |
109|------|-------|-------------|
110| `--heavy` | `-H` | Override Opus model |
111| `--medium` | `-M` | Override Sonnet and Sub-agent models |
112| `--light` | `-l` | Override Haiku model |
113
114#### Individual flags
115
116| Flag | Short | Description |
117|------|-------|-------------|
118| `--opus` | `-o` | Override Opus model |
119| `--sonnet` | `-s` | Override Sonnet model |
120| `--haiku` | `-k` | Override Haiku model |
121| `--agent` | `-a` | Override Sub-agent model |
122
123All other flags are passed through to the `claude` command.
124
125### CLI overrides with flags
126
127#### By group
128
129```fish
130# Set heavy model (Opus) to a specific model
131synclaude --heavy hf:moonshotai/Kimi-K2-Thinking "Your prompt"
132
133# Set medium models (Sonnet, Sub-agent) to GLM-4.6
134synclaude --medium hf:zai-org/GLM-4.6 "Your prompt"
135
136# Set light model (Haiku)
137synclaude --light hf:qwen/Qwen2.5-Coder-32B-Instruct "Your prompt"
138
139# Combine groups
140synclaude --heavy hf:moonshotai/Kimi-K2-Thinking --medium hf:zai-org/GLM-4.6 "Your prompt"
141```
142
143#### By individual model
144
145```fish
146# Override specific models
147synclaude --opus hf:moonshotai/Kimi-K2-Thinking "Your prompt"
148synclaude --sonnet hf:zai-org/GLM-4.6 "Your prompt"
149synclaude --haiku hf:qwen/Qwen2.5-Coder-32B-Instruct "Your prompt"
150synclaude --agent hf:zai-org/GLM-4.6 "Your prompt"
151```
152
153Individual overrides take precedence over group overrides, which take precedence over cached/fallback defaults.
154
155## How it works
156
157`synclaude` configures the following environment variables before invoking
158`claude`:
159
160- `ANTHROPIC_BASE_URL`: Points to Synthetic's Anthropic-compatible endpoint
161- `ANTHROPIC_AUTH_TOKEN`: Your Synthetic API key
162- `ANTHROPIC_DEFAULT_OPUS_MODEL`: Model to use for Opus-tier requests
163- `ANTHROPIC_DEFAULT_SONNET_MODEL`: Model to use for Sonnet-tier requests
164- `ANTHROPIC_DEFAULT_HAIKU_MODEL`: Model to use for Haiku-tier requests
165- `CLAUDE_CODE_SUBAGENT_MODEL`: Model for sub-agent operations
166- `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`: Disabled because telemetry bad
167
168### Caching
169
170Model preferences are stored in `~/.config/synclaude/models.conf` (respects `XDG_CONFIG_HOME`). Use interactive mode (`synclaude i`) to save new defaults.
171
172After each run, it queries the Synthetic API to display:
173
174- Requests used during the session
175- Remaining quota (color-coded badge: green <33%, yellow 33-66%, red >66%)
176
177## Contributions
178
179Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
180new account to contribute, you don't need to fork this repo, you don't need to
181fiddle with `git send-email`, you don't need to faff with your email client to
182get `git request-pull` working...
183
184You just need:
185
186- Git
187- SSH
188- An SSH key
189
190```sh
191# Clone this repo, make your changes, and commit them
192# Create a new patch request with
193git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
194# After potential feedback, submit a revision to an existing patch request with
195git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
196# List patch requests
197ssh pr.pico.sh pr ls amolith/llm-projects
198```
199
200See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
201complete example workflow.
202
203[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
204[pr.pico.sh]: https://pr.pico.sh