{"id":50988571,"url":"https://github.com/adityak74/subagent-fleet","last_synced_at":"2026-06-19T23:02:13.354Z","repository":{"id":365077063,"uuid":"1269784725","full_name":"adityak74/subagent-fleet","owner":"adityak74","description":"Run Claude Code-style subagents across your local model fleet.","archived":false,"fork":false,"pushed_at":"2026-06-15T18:24:02.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T20:15:43.985Z","etag":null,"topics":["claude-code","cli","developer-tools","litellm","local-ai","local-first","ollama","python","subagents"],"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/adityak74.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-15T05:10:12.000Z","updated_at":"2026-06-15T18:25:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adityak74/subagent-fleet","commit_stats":null,"previous_names":["adityak74/subagent-fleet"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/adityak74/subagent-fleet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityak74%2Fsubagent-fleet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityak74%2Fsubagent-fleet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityak74%2Fsubagent-fleet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityak74%2Fsubagent-fleet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adityak74","download_url":"https://codeload.github.com/adityak74/subagent-fleet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityak74%2Fsubagent-fleet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34550858,"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-06-19T02:00:06.005Z","response_time":61,"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":["claude-code","cli","developer-tools","litellm","local-ai","local-first","ollama","python","subagents"],"created_at":"2026-06-19T23:02:12.584Z","updated_at":"2026-06-19T23:02:13.349Z","avatar_url":"https://github.com/adityak74.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# subagent-fleet\n\n**Run Claude Code-style subagents across your local model fleet.**\n\n`subagent-fleet` is a config-first Python CLI for mapping coding subagents to the best Ollama model and machine you own, then generating LiteLLM and Claude Code-style agent configuration.\n\n[![GitHub Repo stars](https://img.shields.io/github/stars/adityak74/subagent-fleet?style=social)](https://github.com/adityak74/subagent-fleet/stargazers)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.10%2B-blue)\n![CLI](https://img.shields.io/badge/interface-CLI-4B5563)\n![Ollama](https://img.shields.io/badge/ollama-compatible-111827)\n![LiteLLM](https://img.shields.io/badge/litellm-ready-2563EB)\n![GitHub last commit](https://img.shields.io/github/last-commit/adityak74/subagent-fleet)\n![GitHub issues](https://img.shields.io/github/issues/adityak74/subagent-fleet)\n\n[Quickstart](#quickstart) • [Configuration](#configuration) • [Generated Files](#generated-files) • [Security](#security) • [Roadmap](#roadmap)\n\n\u003c/div\u003e\n\n## Overview\n\nLocal model users often have more than one useful machine: a laptop, a Mac mini, a workstation, a home server, or a spare GPU box. Most coding harnesses still point at one model endpoint.\n\n`subagent-fleet` turns that setup into a private local subagent fleet:\n\n```text\nplanner     -\u003e small fast model on a lightweight node\nimplementer -\u003e larger coding model on a bigger node\nreviewer    -\u003e larger coding model on a bigger node\nsummarizer  -\u003e small local model on the controller\n```\n\nIt does not replace Ollama, LiteLLM, or Claude Code. It generates the glue between them:\n\n```text\nClaude Code / coding harness\n        |\n        v\nLiteLLM gateway generated by subagent-fleet\n        |\n        +-- Ollama node: laptop\n        +-- Ollama node: Mac mini 64GB\n        +-- Ollama node: workstation\n```\n\n## Features\n\n- Validate a declarative `fleet.yaml`.\n- Discover models from configured Ollama nodes via `/api/tags`.\n- Generate `litellm_config.yaml` with `ollama_chat/` routes.\n- Generate Claude Code-style `.claude/agents/*.md` files.\n- Generate `.env.subagent-fleet` for Claude Code/LiteLLM environment variables.\n- Warm configured Ollama models with `keep_alive`.\n- Show node health and agent routing tables.\n- Keep unreachable nodes isolated so one offline machine does not crash the whole workflow.\n\n## Status\n\nMVP CLI implemented.\n\nAvailable commands:\n\n```bash\nsubagent-fleet init\nsubagent-fleet validate\nsubagent-fleet discover\nsubagent-fleet generate\nsubagent-fleet warmup\nsubagent-fleet status\nsubagent-fleet doctor\nsubagent-fleet clean\nsubagent-fleet skills list\nsubagent-fleet skills install\nsubagent-fleet plugins install\n```\n\n## Install\n\nChoose one of the install paths below.\n\n### CLI from GitHub\n\nInstall the CLI directly from PyPI:\n\n```bash\npython -m pip install subagent-fleet\n```\n\nOr install it as an isolated command with `pipx`:\n\n```bash\npipx install subagent-fleet\n```\n\nVerify:\n\n```bash\nsubagent-fleet --help\n```\n\n### Development Checkout\n\nUse this when contributing to the project:\n\n```bash\ngit clone https://github.com/adityak74/subagent-fleet.git\ncd subagent-fleet\npython -m pip install -e \".[dev]\"\n```\n\nRun tests:\n\n```bash\npython -m pytest\n```\n\n### Claude Code Plugin First\n\nInstall the plugin first from Claude Code, then let the bundled bootstrap skill install the CLI:\n\n```text\n/plugin marketplace add https://github.com/adityak74/subagent-fleet\n/plugin install subagent-fleet\n```\n\nAfter install, ask Claude Code:\n\n```text\nUse the subagent-fleet bootstrap skill to install the CLI and set up this repo.\n```\n\nThe bootstrap skill will run or recommend:\n\n```bash\npython -m pip install subagent-fleet\nsubagent-fleet skills install\n```\n\n### Codex Plugin First\n\nInstall this repository as a local Codex marketplace:\n\n```bash\ncodex plugin marketplace add .\ncodex plugin add subagent-fleet@subagent-fleet\n```\n\nThen ask Codex:\n\n```text\nUse the subagent-fleet bootstrap skill to install the CLI and set up this repo.\n```\n\n## Quickstart\n\nCreate a starter config:\n\n```bash\nsubagent-fleet init\n```\n\nEdit `fleet.yaml` with your Ollama node endpoints and model names, then validate it:\n\n```bash\nsubagent-fleet validate\n```\n\nCheck which nodes are reachable:\n\n```bash\nsubagent-fleet discover\n```\n\nGenerate LiteLLM, Claude agent, and environment files:\n\n```bash\nsubagent-fleet generate\n```\n\nStart LiteLLM:\n\n```bash\nexport LITELLM_MASTER_KEY=\"sk-local-dev\"\n\nlitellm \\\n  --config ./litellm_config.yaml \\\n  --host 127.0.0.1 \\\n  --port 4000\n```\n\nPoint Claude Code at the local gateway:\n\n```bash\nsource .env.subagent-fleet\nclaude\n```\n\n## Configuration\n\n`subagent-fleet` is driven by `fleet.yaml`.\n\n```yaml\nproject:\n  name: local-dev\n  gateway:\n    provider: litellm\n    host: 127.0.0.1\n    port: 4000\n    master_key_env: LITELLM_MASTER_KEY\n\nnodes:\n  m5-local:\n    endpoint: http://localhost:11434\n    tags: [controller, local, fast]\n\n  m4-mini-64gb:\n    endpoint: http://192.168.1.50:11434\n    tags: [heavy, coder, reviewer]\n\n  m4-mini-16gb:\n    endpoint: http://192.168.1.51:11434\n    tags: [small, planner, summarizer]\n\nmodels:\n  heavy-coder:\n    node: m4-mini-64gb\n    ollama_model: qwen2.5-coder:32b\n    litellm_alias: claude-sonnet-local\n    context: 32768\n    timeout: 600\n    max_parallel: 1\n\n  small-coder:\n    node: m4-mini-16gb\n    ollama_model: qwen2.5-coder:7b\n    litellm_alias: claude-haiku-local\n    context: 8192\n    timeout: 300\n    max_parallel: 1\n\nagents:\n  planner:\n    model: small-coder\n    description: Use for planning, file discovery, task decomposition, and summarization.\n    tools: [Read, Grep, Glob]\n    prompt: |\n      You are a fast local planning agent.\n      Do not edit files.\n      Return a concise response with:\n      - plan\n      - relevant files\n      - risks\n      - next recommended agent\n\n  implementer:\n    model: heavy-coder\n    description: Use for implementation, bug fixes, refactors, and patch creation.\n    tools: [Read, Grep, Glob, Edit, MultiEdit, Bash]\n\n  reviewer:\n    model: heavy-coder\n    description: Use after implementation to review diffs, tests, regressions, and maintainability.\n    tools: [Read, Grep, Glob, Bash]\n```\n\n## Generated Files\n\nRunning:\n\n```bash\nsubagent-fleet generate\n```\n\ncreates:\n\n```text\nlitellm_config.yaml\n.claude/agents/planner.md\n.claude/agents/implementer.md\n.claude/agents/reviewer.md\n.env.subagent-fleet\n```\n\nExample LiteLLM route:\n\n```yaml\nmodel_list:\n  - model_name: claude-sonnet-local\n    litellm_params:\n      model: ollama_chat/qwen2.5-coder:32b\n      api_base: http://192.168.1.50:11434\n      api_key: ollama\n      timeout: 600\n    model_info:\n      max_input_tokens: 32768\n```\n\nExample Claude agent:\n\n```markdown\n---\nname: planner\ndescription: Use for planning, file discovery, task decomposition, and summarization.\nmodel: claude-haiku-local\ntools: Read, Grep, Glob\n---\n\nYou are a fast local planning agent.\nDo not edit files.\nReturn a concise response with:\n- plan\n- relevant files\n- risks\n- next recommended agent\n```\n\n## Commands\n\n| Command | Purpose |\n| --- | --- |\n| `subagent-fleet init` | Create a starter `fleet.yaml`. |\n| `subagent-fleet validate` | Validate schema, references, URLs, aliases, and agent names. |\n| `subagent-fleet discover` | Query configured Ollama nodes for available models. |\n| `subagent-fleet generate` | Generate LiteLLM config, Claude agents, and env file. |\n| `subagent-fleet warmup` | Preload configured Ollama models with `keep_alive`. |\n| `subagent-fleet status` | Show node health and agent routing. |\n| `subagent-fleet doctor` | Show validation and local-network safety guidance. |\n| `subagent-fleet clean` | List or remove generated files. |\n| `subagent-fleet skills list` | List bundled assistant skills and supported targets. |\n| `subagent-fleet skills install` | Install assistant-facing setup and operations skills. |\n| `subagent-fleet plugins install` | Install Claude Code and Codex plugin marketplace bundles. |\n\nJSON output is available for discovery and status:\n\n```bash\nsubagent-fleet discover --json\nsubagent-fleet status --json\n```\n\n## Assistant Skills\n\n`subagent-fleet` ships assistant-facing skills that teach Claude Code, Codex, OpenCode, and similar tools how to set up and operate the fleet from inside a repository.\n\nList bundled skills and supported targets:\n\n```bash\nsubagent-fleet skills list\n```\n\nInstall all bundled skills for all supported targets:\n\n```bash\nsubagent-fleet skills install\n```\n\nThis writes:\n\n```text\n.claude/skills/subagent-fleet-setup/SKILL.md\n.claude/skills/subagent-fleet-operations/SKILL.md\n.codex/skills/subagent-fleet-setup/SKILL.md\n.codex/skills/subagent-fleet-operations/SKILL.md\n.opencode/skills/subagent-fleet-setup/SKILL.md\n.opencode/skills/subagent-fleet-operations/SKILL.md\n```\n\nInstall for a specific assistant:\n\n```bash\nsubagent-fleet skills install --target codex\nsubagent-fleet skills install --target claude-code\nsubagent-fleet skills install --target opencode\n```\n\nInstall one bundled skill:\n\n```bash\nsubagent-fleet skills install --skill subagent-fleet-setup\n```\n\nExisting skill files are not overwritten unless you pass `--force`.\n\n## Plugin Marketplaces\n\nThis repository also ships plugin marketplace metadata so users can install the assistant skill first, then let that skill install and verify the Python CLI.\n\nIncluded plugin artifacts:\n\n```text\n.claude-plugin/marketplace.json\n.agents/plugins/marketplace.json\nplugins/subagent-fleet/.claude-plugin/plugin.json\nplugins/subagent-fleet/.codex-plugin/plugin.json\nplugins/subagent-fleet/skills/subagent-fleet-bootstrap/SKILL.md\nplugins/subagent-fleet/skills/subagent-fleet-setup/SKILL.md\nplugins/subagent-fleet/skills/subagent-fleet-operations/SKILL.md\n```\n\nThe bootstrap skill teaches Claude Code or Codex how to install the CLI:\n\n```bash\npython -m pip install subagent-fleet\n```\n\nand then install repo-local assistant skills:\n\n```bash\nsubagent-fleet skills install\n```\n\nClaude Code plugin install flow:\n\n```text\n/plugin marketplace add https://github.com/adityak74/subagent-fleet\n/plugin install subagent-fleet\n```\n\nCodex local marketplace flow:\n\n```bash\ncodex plugin marketplace add .\ncodex plugin add subagent-fleet@subagent-fleet\n```\n\nTo generate the same marketplace/plugin bundle into another directory:\n\n```bash\nsubagent-fleet plugins install --out /path/to/marketplace-root\n```\n\nInstall only one target:\n\n```bash\nsubagent-fleet plugins install --target claude-code\nsubagent-fleet plugins install --target codex\n```\n\nExisting plugin marketplace files are not overwritten unless you pass `--force`.\n\n## Ollama Worker Setup\n\nOn each worker machine, run Ollama on a private interface reachable from your controller:\n\n```bash\nlaunchctl setenv OLLAMA_HOST \"0.0.0.0:11434\"\nlaunchctl setenv OLLAMA_KEEP_ALIVE \"-1\"\nlaunchctl setenv OLLAMA_NUM_PARALLEL \"1\"\nlaunchctl setenv OLLAMA_MAX_LOADED_MODELS \"1\"\n\nkillall Ollama\nopen -a Ollama\n```\n\nFrom the controller:\n\n```bash\ncurl http://NODE_IP:11434/api/tags\n```\n\n## Security\n\n`subagent-fleet` assumes private local networking.\n\nDo:\n\n- Use LAN, firewall rules, Tailscale, WireGuard, or a private subnet.\n- Keep `LITELLM_MASTER_KEY` set for LiteLLM access.\n- Treat generated `.env.subagent-fleet` files as local developer configuration.\n\nDo not:\n\n- Expose Ollama directly to the public internet.\n- Expose LiteLLM without authentication.\n- Commit real API keys, LAN secrets, or machine-specific private `.env` files.\n\nRun:\n\n```bash\nsubagent-fleet doctor\n```\n\nfor local setup and safety reminders.\n\n## Development\n\nInstall dev dependencies:\n\n```bash\npython -m pip install -e \".[dev]\"\n```\n\nRun tests:\n\n```bash\npython -m pytest\n```\n\nRun a focused test:\n\n```bash\npython -m pytest tests/test_config.py\n```\n\nCheck CLI wiring:\n\n```bash\npython -m subagent_fleet.cli --help\n```\n\n## Project Layout\n\n```text\nsrc/subagent_fleet/\n  cli.py\n  config.py\n  discovery.py\n  plugins.py\n  warmup.py\n  status.py\n  skills.py\n  generators/\n  skill_templates/\n  templates/\n\nexamples/\nplugins/\ntests/\n```\n\n## Roadmap\n\nMVP:\n\n- [x] `fleet.yaml` schema\n- [x] Ollama node health checks\n- [x] Ollama model discovery via `/api/tags`\n- [x] LiteLLM config generation\n- [x] Claude Code agent generation\n- [x] Environment file generation\n- [x] Model warmup with `keep_alive`\n- [x] Status and routing tables\n\nNext:\n\n- [ ] Latency benchmarking\n- [ ] Recommended agent-to-node assignment\n- [ ] Role-based routing templates\n- [ ] Tailscale-aware node discovery\n- [ ] OpenAI-compatible harness examples\n- [ ] Release packaging\n\nLater:\n\n- [ ] Dynamic routing by task type\n- [ ] Fallback model generation\n- [ ] Queue-aware scheduling\n- [ ] Agent execution trace viewer\n- [ ] Support for vLLM, LM Studio, llama.cpp, OpenRouter, and cloud APIs\n\n## Star History\n\n\u003ca href=\"https://star-history.com/#adityak74/subagent-fleet\u0026Date\"\u003e\n  \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=adityak74/subagent-fleet\u0026type=Date\" /\u003e\n\u003c/a\u003e\n\n## Contributing\n\nIssues and pull requests are welcome.\n\nGood first areas:\n\n- More generator tests\n- Additional example fleets\n- Better status formatting\n- More robust Ollama error reporting\n- Documentation for real multi-machine setups\n\nBefore opening a PR:\n\n```bash\npython -m pytest\n```\n\n## What This Is Not\n\n`subagent-fleet` is not:\n\n- an inference engine\n- a replacement for Ollama\n- a replacement for LiteLLM\n- a model sharding framework\n- Kubernetes for local LLMs\n- a public model hosting platform\n\nIt is a small workflow layer for private local subagent orchestration.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityak74%2Fsubagent-fleet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadityak74%2Fsubagent-fleet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityak74%2Fsubagent-fleet/lists"}