diff --git a/AGENTS.md b/AGENTS.md index 22f26a83c516e522db7b2ffb829f5736d263bd04..b670c97cbacf2742ca344c809e165e1f726f3dff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/.fish` if it exists +2. Load agent definition from `fish/functions/_synu_agents/.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/.fish` can provide five functions: +Each agent definition in `fish/functions/_synu_agents/.fish` can provide five functions: 1. **`_synu_agent__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/.fish` +1. Create `fish/functions/_synu_agents/.fish` 2. Add SPDX header 3. Source cache functions: `source (status dirname)/../_synu_cache.fish` 4. Define fallback default: `set -g _synu__fallback_model "hf:..."` @@ -351,7 +354,7 @@ This project has no automated test suite. Testing is manual: 8. Define `_synu_agent__args` (if agent uses CLI args for model) 9. Define `_synu_agent__env_vars` (if agent uses env vars) 10. Optionally define `_synu_agent__interactive` (for `synu i `) -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 | |-------|--------|---------------------|-------------| diff --git a/README.md b/README.md index 6a5cd34976b252f4285b6e22437b29af7feab6e2..76490f81e492e1a0c7cb4751b97c438d1e700bf1 100644 --- a/README.md +++ b/README.md @@ -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 ```