{"id":51312386,"url":"https://github.com/phytonking/swap","last_synced_at":"2026-07-01T05:01:58.385Z","repository":{"id":365393262,"uuid":"1271895161","full_name":"Phytonking/swap","owner":"Phytonking","description":"Route an AI coding agent's mechanical sub-tasks (summarize, extract, classify, code) to cheap local or cloud models — save frontier tokens. Works with Claude Code, Codex, Cursor, opencode, and more.","archived":false,"fork":false,"pushed_at":"2026-06-17T05:40:34.000Z","size":60,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T07:21:52.009Z","etag":null,"topics":["agent-skills","ai-agents","claude-code","codex","llm","llm-cost","local-llm","ollama","opencode"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Phytonking.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-17T05:28:36.000Z","updated_at":"2026-06-17T05:40:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Phytonking/swap","commit_stats":null,"previous_names":["phytonking/swap"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Phytonking/swap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Phytonking%2Fswap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Phytonking%2Fswap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Phytonking%2Fswap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Phytonking%2Fswap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Phytonking","download_url":"https://codeload.github.com/Phytonking/swap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Phytonking%2Fswap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34993438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","claude-code","codex","llm","llm-cost","local-llm","ollama","opencode"],"created_at":"2026-07-01T05:01:56.233Z","updated_at":"2026-07-01T05:01:58.361Z","avatar_url":"https://github.com/Phytonking.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🔀 swap\n\n**Route an agent's grunt work to a cheap model. Keep the reasoning on the frontier.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![CI](https://github.com/Phytonking/swap/actions/workflows/ci.yml/badge.svg)](https://github.com/Phytonking/swap/actions/workflows/ci.yml)\n[![install: skills.sh](https://img.shields.io/badge/install-skills.sh-black)](https://skills.sh)\n[![deps: none](https://img.shields.io/badge/runtime%20deps-none-brightgreen)](skills/swap/swap.py)\n\n\u003c/div\u003e\n\n`swap` is a tiny CLI + agent skill. It lets your AI coding agent hand off\nmechanical sub-tasks — digesting logs, extracting structured data, yes/no\ntriage, drafting boilerplate — to a cheap **local (Ollama)** or **cloud** model,\ninstead of spending frontier tokens (and context) on them.\n\n```bash\nswap summarize \"what failed and where\"          \u003c build.log\nswap extract --json \"errors with file + line\"   \u003c build.log   # -\u003e [{\"file\":\"…\",\"line\":42}, …]\nswap classify --json \"flaky test or real?\"      \u003c ci.log      # -\u003e {\"label\":\"flaky\",\"confidence\":0.9}\nswap code \"add a null check on line 42\"         \u003c handler.ts\n```\n\nContext on **stdin**, instruction as the argument. The agent spends ~20 tokens\nissuing the call instead of reading a 2000-line log into its own context — then\nreasons over the distilled result. Delegation is always **explicit**; the local\npath sends **nothing** off your machine.\n\n## Install\n\n```bash\n# any of 70+ agents (Claude Code, Cursor, Codex, Gemini CLI, opencode, Zed, …)\nnpx skills add Phytonking/swap\n\n# or, no Node — bootstraps the router + prints harness wiring:\ncurl -fsSL https://raw.githubusercontent.com/Phytonking/swap/main/install.sh | sh\n```\n\nFirst use auto-bootstraps (`doctor --ensure`): detects your Ollama, picks the\nbest model, installs a stable `~/.swap/bin/swap`. No local model? It offers\n`ollama pull qwen3:8b`. Full per-harness matrix: **[INSTALL.md](INSTALL.md)**.\n\n## Intents\n\n| Intent | For | Output |\n|---|---|---|\n| `summarize` | digest a big log / dump | text |\n| `extract` | pull structured data | JSON |\n| `classify` | yes/no triage | JSON `{label, confidence}` |\n| `code` | draft mechanical code/diff | text |\n\nFlags: `--tier cheap\\|fast\\|local` · `-m backend/model` · `--json`.\n\n## Works with your harness\n\nOne rule file — the [`AGENTS.md`](AGENTS.md) open standard — drives them all:\n\n| Harness | Reads |\n|---|---|\n| Claude Code | Agent Skill / `CLAUDE.md` |\n| Codex · opencode · Windsurf · Cursor · Cline | `AGENTS.md` |\n| Gemini CLI | `GEMINI.md` |\n| Aider · any shell agent | `CONVENTIONS.md` / system prompt |\n\nThe agent only needs to run shell commands and read a rule file.\n\n## Slash commands (Claude Code)\n\nInstalled as a plugin, swap adds user-invoked commands:\n\n| Command | Does |\n|---|---|\n| `/swap:report` | show how much you've saved routing to cheap models |\n| `/swap:doctor` | detect/configure backends and show readiness |\n| `/swap:add-model gemini gemini-2.5-flash` | add a cloud model + store its key |\n\nInstall the plugin to get them:\n\n```\n/plugin marketplace add Phytonking/swap\n/plugin install swap@swap\n```\n\nThe model-invoked skill works in every harness; these are a Claude Code convenience.\n\n## Backends\n\n**Local (default, free, private):** Ollama at `localhost:11434`. `doctor`\nauto-detects installed models and prioritizes a sensible default (family → size;\ncoder checkpoints reserved for `code`).\n\n**Cloud (off by default):** when an agent needs a cloud model, swap emits a\nstructured `NEEDS_KEY` signal so the agent can ask you for *that model's* key:\n\n```bash\nswap add-backend gemini --model gemini-2.5-flash   # presets: gemini, openai,\n                                                   # openrouter, groq, deepinfra, …\nswap set-key gemini        # key read hidden on stdin, stored ~/.swap/config.json\n                           # (mode 600) — never in a repo, an argument, or the chat\n```\n\nswap routes to it automatically thereafter.\n\n## Is the cheap model good enough? Measure it.\n\n```bash\npython3 eval/eval_applicability.py   # SAFE / RISKY / UNSAFE per intent × model\n```\n\n```\nmodel                 mechanical  judgment  class\nqwen3.5:9b               1.00       1.00     reasoning   # safe for judgment + grunt work\ngemma3:4b                1.00       0.80     workhorse   # grunt work only\ndeepseek-coder:6.7b      0.78       0.60     code-only   # code drafting only\n```\n\nDeterministic, free, offline. Methodology: **[EVAL.md](EVAL.md)**.\n\n## How it works\n\n```\nswap \u003cintent\u003e \"\u003cinstruction\u003e\"  \u003cstdin\u003e\n        │  resolve intent → tier → backend (config-driven)\n        │  fit context to the model's window · temperature 0 · repair JSON\n        ▼\n   Ollama (local)  or  any OpenAI-compatible cloud\n        │\n        ▼  result on stdout   +   one line appended to ~/.swap/trace.jsonl\n   swap report   →   \"saved ~$X routing to cheap models instead of the frontier\"\n```\n\n- **Explicit, never silent** — no proxy, no env-var hijacking, no auto-routing.\n- **Zero runtime deps** — one self-contained Python stdlib file, runs on any `python3 ≥ 3.8`.\n- **Keys stay private** — only in `~/.swap/config.json` (mode 600).\n\n## Layout\n\n```\nskills/swap/swap.py   the router (CLI + skill) — stdlib only\nskills/swap/SKILL.md  Claude Code skill (self-bootstrapping)\nAGENTS.md CLAUDE.md GEMINI.md   per-harness rule files\n.claude-plugin/ commands/       Claude Code plugin + slash commands\neval/                 SAFE/RISKY/UNSAFE verdict harness + corpus\ntests/                stdlib unittest smoke tests (CI)\ninstall.sh INSTALL.md\n```\n\n## Contributing\n\nSee **[CONTRIBUTING.md](CONTRIBUTING.md)**. Two hard rules: the router stays\n**zero-dependency** (stdlib only), and delegation stays **explicit**.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphytonking%2Fswap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphytonking%2Fswap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphytonking%2Fswap/lists"}