@@ -21,20 +21,22 @@ This document helps AI agents work effectively with the synu codebase.
### Architecture
```
-synu (main wrapper)
- ├─ _synu_get_quota (API quota fetching)
- ├─ _synu_cache (model preference persistence)
- └─ _synu_agents/ (agent-specific configuration)
- ├─ claude.fish (Claude Code: env vars, multi-model)
- ├─ opencode.fish (OpenCode: CLI args)
- ├─ aider.fish (Aider: env vars + CLI args)
- ├─ llxprt.fish (llxprt: CLI args only)
- └─ qwen.fish (Qwen Code: env vars)
+fish/
+└─ functions/
+ ├─ synu.fish (main wrapper)
+ ├─ _synu_get_quota.fish (API quota fetching)
+ ├─ _synu_cache.fish (model preference persistence)
+ └─ _synu_agents/
+ ├─ claude.fish (Claude Code: env vars, multi-model)
+ ├─ opencode.fish (OpenCode: CLI args)
+ ├─ aider.fish (Aider: env vars + CLI args)
+ ├─ llxprt.fish (llxprt: CLI args only)
+ └─ qwen.fish (Qwen Code: env vars)
```
**Control Flow:**
1. Parse arguments (check for interactive mode, agent name)
-2. Load agent definition from `functions/_synu_agents/<agent>.fish` if it exists
+2. Load agent definition from `fish/functions/_synu_agents/<agent>.fish` if it exists
3. Parse agent-specific flags using `argparse` with `--ignore-unknown` for passthrough
4. Configure agent environment (if agent has `_configure` function)
5. Fetch initial quota from Synthetic API
@@ -51,21 +53,22 @@ synu (main wrapper)
## File Structure
```
-├── functions/
-│ ├── synu.fish # Main wrapper function
-│ ├── _synu_get_quota.fish # Private: Fetch quota from API
-│ ├── _synu_cache.fish # Private: Model preference cache
-│ └── _synu_agents/
-│ ├── claude.fish # Claude Code agent configuration
-│ ├── opencode.fish # OpenCode agent configuration
-│ ├── aider.fish # Aider agent configuration
-│ ├── llxprt.fish # llxprt agent configuration
-│ └── qwen.fish # Qwen Code agent configuration
-├── completions/
-│ └── synu.fish # Shell completions
-├── crush.json # LSP configuration (fish-lsp)
-├── README.md # User documentation
-└── .gitignore # Ignore agent working directories
+├── fish/
+│ ├── functions/
+│ │ ├── synu.fish # Main wrapper function
+│ │ ├── _synu_get_quota.fish # Private: Fetch quota from API
+│ │ ├── _synu_cache.fish # Private: Model preference cache
+│ │ └── _synu_agents/
+│ │ ├── claude.fish # Claude Code agent configuration
+│ │ ├── opencode.fish # OpenCode agent configuration
+│ │ ├── aider.fish # Aider agent configuration
+│ │ ├── llxprt.fish # llxprt agent configuration
+│ │ └── qwen.fish # Qwen Code agent configuration
+│ └── completions/
+│ └── synu.fish # Shell completions
+├── crush.json # LSP configuration (fish-lsp)
+├── README.md # User documentation
+└── .gitignore # Ignore agent working directories
```
## Essential Commands
@@ -76,9 +79,9 @@ This is a Fish shell library with no build system. Key commands:
```fish
# Source the function (from repo root)
-source functions/synu.fish
-source functions/_synu_get_quota.fish
-source functions/_synu_cache.fish
+source fish/functions/synu.fish
+source fish/functions/_synu_get_quota.fish
+source fish/functions/_synu_cache.fish
# Check quota only
synu
@@ -102,7 +105,7 @@ synu aider --model hf:some/model --editor-model hf:other/model "prompt"
```fish
# Install via fundle (in a clean fish instance)
-fundle plugin 'synu' --url 'https://git.secluded.site/amolith/llm-projects'
+fundle plugin 'synu' --url 'https://git.secluded.site/synu' --path 'fish'
fundle install
fundle init
```
@@ -111,11 +114,11 @@ fundle init
```fish
# Validate Fish syntax
-fish -n functions/synu.fish
-fish -n functions/_synu_get_quota.fish
-fish -n functions/_synu_cache.fish
-fish -n functions/_synu_agents/*.fish
-fish -n completions/synu.fish
+fish -n fish/functions/synu.fish
+fish -n fish/functions/_synu_get_quota.fish
+fish -n fish/functions/_synu_cache.fish
+fish -n fish/functions/_synu_agents/*.fish
+fish -n fish/completions/synu.fish
```
### LSP Integration
@@ -143,7 +146,7 @@ The project includes `crush.json` configuring `fish-lsp` for Fish language suppo
### Agent Configuration Pattern
-Each agent definition in `functions/_synu_agents/<agent>.fish` can provide five functions:
+Each agent definition in `fish/functions/_synu_agents/<agent>.fish` can provide five functions:
1. **`_synu_agent_<name>_flags`** - Returns argparse flag specification (one per line)
```fish
@@ -341,7 +344,7 @@ This project has no automated test suite. Testing is manual:
### Adding a New Agent Configuration
-1. Create `functions/_synu_agents/<agent>.fish`
+1. Create `fish/functions/_synu_agents/<agent>.fish`
2. Add SPDX header
3. Source cache functions: `source (status dirname)/../_synu_cache.fish`
4. Define fallback default: `set -g _synu_<agent>_fallback_model "hf:..."`
@@ -351,7 +354,7 @@ This project has no automated test suite. Testing is manual:
8. Define `_synu_agent_<agent>_args` (if agent uses CLI args for model)
9. Define `_synu_agent_<agent>_env_vars` (if agent uses env vars)
10. Optionally define `_synu_agent_<agent>_interactive` (for `synu i <agent>`)
-11. Update `completions/synu.fish` to add the new agent to suggestions
+11. Update `fish/completions/synu.fish` to add the new agent to suggestions
12. Test manually
### Modifying Quota Display
@@ -369,7 +372,7 @@ Both use the same color thresholds:
```fish
# Test quota fetch directly
-source functions/_synu_get_quota.fish
+source fish/functions/_synu_get_quota.fish
set -gx SYNTHETIC_API_KEY your_key_here
_synu_get_quota
# Should output: "requests_used limit"
@@ -395,7 +398,7 @@ echo ~/.config/synu/models.conf
cat ~/.config/synu/models.conf
# Test cache functions
-source functions/_synu_cache.fish
+source fish/functions/_synu_cache.fish
_synu_cache_set test model hf:test/model
_synu_cache_get test model
```
@@ -404,7 +407,7 @@ _synu_cache_get test model
**Example: Claude with flag override**
1. User runs: `synu claude --large hf:some/model "prompt"`
-2. `synu.fish` loads `functions/_synu_agents/claude.fish`
+2. `synu.fish` loads `fish/functions/_synu_agents/claude.fish`
3. Calls `_synu_agent_claude_flags` to get flag spec
4. Parses with `argparse --ignore-unknown` → sets `_flag_large`
5. Rebuilds flags for configure: `--large=hf:some/model`
@@ -417,7 +420,7 @@ _synu_cache_get test model
**Example: OpenCode with CLI args**
1. User runs: `synu opencode "prompt"`
-2. `synu.fish` loads `functions/_synu_agents/opencode.fish`
+2. `synu.fish` loads `fish/functions/_synu_agents/opencode.fish`
3. `_configure` sets `_synu_opencode_selected_model` from cache/fallback
4. `_args` returns: `--model synthetic/hf:MiniMaxAI/MiniMax-M2`
5. Executes: `command opencode -m "synthetic/hf:..." "prompt"`
@@ -473,7 +476,7 @@ Synthetic provides a unified API for multiple LLM providers with quota tracking.
### Configured Agents
-Agents with specific configurations in `functions/_synu_agents/`:
+Agents with specific configurations in `fish/functions/_synu_agents/`:
| Agent | Models | Configuration Method | Interactive |
|-------|--------|---------------------|-------------|
@@ -31,7 +31,7 @@ gain support!)
Add to your `~/.config/fish/config.fish`:
```fish
-fundle plugin 'synu' --url 'https://git.secluded.site/synu'
+fundle plugin 'synu' --url 'https://git.secluded.site/synu' --path 'fish'
fundle init
```