agents-fleet 0.5.0__py3-none-any.whl

agents_fleet-0.5.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: agents-fleet
+Version: 0.5.0
+Summary: Give Claude Code, Codex and Gemini every machine you have: a live GPU, VRAM, RAM and disk inventory across your servers, SSH access between them, and an MCP server.
+Project-URL: Homepage, https://github.com/lion-zhang/fleet
+Project-URL: Documentation, https://github.com/lion-zhang/fleet/blob/main/docs/getting-started.md
+Project-URL: Issues, https://github.com/lion-zhang/fleet/issues
+Author: Lin Zhang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,codex,coding-agent,devops,gemini-cli,gpu,gpu-monitoring,homelab,inventory,mcp,mcp-server,mlops,nvidia,remote-execution,runpod,ssh,ssh-keys,vast-ai,vram
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Clustering
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: filelock>=3.13
+Requires-Dist: mcp>=2
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: mcp
+Provides-Extra: migrate
+Requires-Dist: pyrage>=1.1; extra == 'migrate'
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.lion-zhang/fleet -->
+<div align="center">
+
+# fleet — let your coding agent use every machine you have
+
+**Claude Code, Codex and Gemini see one machine: the one they run on.<br>
+fleet shows them all of yours — every GPU, how much is free, and how to get there.**
+
+[![tests](https://github.com/lion-zhang/fleet/actions/workflows/test.yml/badge.svg)](https://github.com/lion-zhang/fleet/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Linux | macOS | Windows](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey.svg)
+![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2.svg)
+
+<img src="docs/assets/fleet-ls.svg" alt="fleet ls: free GPU, VRAM, CPU, RAM and disk across seven machines — an A100 rental with one busy and one idle card, an idle H100 rental flagged as costing money, a busy RTX 3090 box with a nearly full disk, a laptop, a NAS and a machine that is switched off" width="100%">
+
+</div>
+
+## The problem
+
+Ask your agent to train a model and it starts on your laptop — while a 4090 sits idle
+across the room and a rented A100 bills you by the hour. It cannot use what it cannot see.
+
+- **Your agent is stuck on one machine.** It has no idea your other boxes exist.
+- **Finding a free GPU is manual.** SSH into five hosts, run `nvidia-smi`, compare in your head.
+- **Handing it a server means pasting credentials** into the chat, and hoping.
+
+## Install once, then just talk to your agent
+
+On the machine you work from:
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/lion-zhang/fleet/main/install.sh | sh
+```
+
+<sub>Windows: `powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/lion-zhang/fleet/main/install.ps1 | iex"`</sub>
+
+That is the whole setup. This machine becomes your fleet's **center**, and every
+[supported agent](docs/agents.md) installed on it learns fleet. From here on you say what you want in plain words —
+no commands to remember. When something is missing, the agent asks (illustrative):
+
+> **You:** add my new GPU server
+>
+> **Agent:** Sure — how do you usually connect to it? An SSH command like
+> `ssh -p 40001 root@1.2.3.4` is all I need.
+>
+> **You:** `ssh ubuntu@10.0.0.7`
+>
+> **Agent:** Added as `gpu-box`: 2× RTX 4090, both idle, 46 GB free. It's ready to use.
+
+> **You:** train `train.py` on whatever has a free 24 GB card
+>
+> **Agent:** `rtx4090` has 23.1 GB free and an idle GPU; `a100-spot` is free too but costs
+> $1.89/hr. Starting on `rtx4090`, logging to `train.log`.
+
+| You say | What happens |
+|---|---|
+| "what's free right now?" | every machine checked, the free ones listed |
+| "find me a box with a 24 GB card" | machines matched by what they have, not by name |
+| "run the tests on the Linux box" | run there, results brought back |
+| "what's costing me money?" | idle paid rentals flagged, with their hourly price |
+| "let the laptop reach the NAS" | access granted, applied at once |
+| "add a machine without typing its password" | a one-time line to paste there; it joins by itself |
+
+No hostnames, keys or passwords go into the conversation, and anything irreversible
+waits for your yes.
+
+Every machine besides the center is a **member**. A member needs nothing installed —
+just sshd. For machines where you also want to *run* fleet, or that you would rather not
+type a password for, the agent gives you an invite line: pasted there, it installs fleet
+and joins by itself.
+
+### Already in your agent? Install from there
+
+| Agent | Install |
+|---|---|
+| **Claude Code** | `/plugin marketplace add lion-zhang/fleet` then `/plugin install fleet@fleet` |
+| **Codex** | `codex plugin marketplace add lion-zhang/fleet` then `codex plugin add fleet@fleet` |
+| **Gemini CLI** | `gemini extensions install https://github.com/lion-zhang/fleet` |
+| **GitHub Copilot CLI** | `copilot plugin marketplace add lion-zhang/fleet` then `copilot plugin install fleet@fleet` |
+| **Cursor** | [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=fleet&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJhZ2VudC1mbGVldCIsIm1jcCJdfQ%3D%3D) |
+| **VS Code** | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_fleet-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=fleet&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22agents-fleet%22%2C%22mcp%22%5D%7D) |
+| **Claude Desktop** | open `fleet.mcpb` from the [latest release](https://github.com/lion-zhang/fleet/releases/latest) |
+
+Plus OpenCode, Amp, Windsurf, Cline, Zed, Qwen Code, Goose, Kiro, Hermes — 35+ agents in all:
+**[every agent →](docs/agents.md)**
+
+On a machine in no fleet yet, these make it a center on first use, like the installer.
+For a member, paste its invite line first.
+
+## Built to be safe
+
+- **Nothing to install on your machines.** fleet probes with one script over one SSH
+  connection — Linux, macOS or Windows. A NAS or a fresh rental works as it is.
+- **Keys, not passwords.** A password, if needed at all, is typed once by you. Nothing
+  that could be stolen is stored, and the agent never sees a credential.
+- **Access you control.** The center decides which machine may reach which, and a revoke
+  is pushed at once. `fleet access gpu-box --allow laptop`, `--deny` to take it back.
+- **The agent asks, not guesses.** It is told to ask which machine you mean, and to leave
+  irreversible commands to you.
+
+## Prefer the command line?
+
+Everything the agent does is a plain `fleet` command, for when you want to drive it
+yourself:
+
+```bash
+fleet ls                            # every machine, with what is free right now
+fleet ls --tag cuda --tag vram-24g  # by capability: NVIDIA, a card of 24 GB or more
+fleet top                           # live view, like htop for the whole fleet
+fleet show gpu-box                  # one machine in detail: GPU processes, services, disks
+fleet ssh gpu-box -- nvidia-smi     # run something there
+fleet add "ssh ubuntu@10.0.0.7"     # add a machine; fleet invite NAME for a join line
+fleet access nas --allow laptop     # let one machine reach another
+```
+
+<img src="docs/assets/fleet-top.svg" alt="fleet top: a live view of GPU utilisation, free VRAM, CPU, RAM and disk across all machines" width="100%">
+
+Rentals from vast.ai, RunPod or Lambda show their price (`fleet edit a100 --cost 1.89`),
+the fleet's burn rate, and an alert when a paid machine sits idle. On Tailscale, ZeroTier
+or WireGuard? fleet just needs an address it can route to.
+
+## How fleet compares
+
+fleet is about the machines you already have. It complements tools that launch new ones.
+
+| | `ssh` + `nvidia-smi` | nvitop / gpustat | SkyPilot / dstack | **fleet** |
+|---|:---:|:---:|:---:|:---:|
+| All your machines in one view | ✗ | ✗ one machine | ✓ the ones it manages | ✓ |
+| Built for coding agents (skill / MCP) | ✗ | ✗ | partly | ✓ |
+| Nothing installed on target machines | ✓ | ✗ | ✗ | ✓ |
+| Manages SSH access between machines | ✗ | ✗ | for its own clusters | ✓ |
+| Launches new cloud VMs | ✗ | ✗ | ✓ | ✗ |
+
+## FAQ
+
+<details>
+<summary><b>I use Claude Code <i>and</i> Codex (and more) on one machine. Does that work?</b></summary>
+
+Yes — that is the normal case. fleet is installed once per machine: one command, one
+inventory, one set of keys. Each agent only gets a small skill or MCP entry pointing at
+it, so Claude Code, Codex, Gemini CLI and a desktop app all see the same machines, and can
+use them at the same time. Install a new agent later? Run `fleet setup` (or ask an agent
+that already has fleet to do it).
+</details>
+
+<details>
+<summary><b>What does my agent actually get?</b></summary>
+
+Agents with a shell (Claude Code, Codex, Gemini CLI, Copilot CLI, OpenCode, …) get a
+skill — text that tells them the `fleet` commands; it costs nothing until a task needs a
+machine. Apps that cannot run commands (Claude Desktop, Cursor, VS Code, …) get an MCP
+server that runs the same commands for them. The installer sets up the supported agents
+you have; [docs/agents.md](docs/agents.md) has the details for each.
+</details>
+
+<details>
+<summary><b>Does it work behind NAT, or across sites?</b></summary>
+
+The center needs an address it can route to: a public IP, a LAN, or an overlay such as
+Tailscale. A machine the center cannot dial can still join with the `fleet invite` line
+and report in; granting access to it waits until the center can reach it.
+</details>
+
+<details>
+<summary><b>What if the center is off?</b></summary>
+
+Normal — it can be a laptop that is closed half the day. Everything already granted keeps
+working; only changes wait for it. Move the role with `fleet center NAME`.
+</details>
+
+<details>
+<summary><b>Windows?</b></summary>
+
+Yes, both ways. A Windows machine works as a target with OpenSSH Server and nothing else,
+and fleet runs on Windows too, center included: interactive `fleet ssh`, `fleet top` and
+the background service all work there. See [Windows](docs/getting-started.md#windows).
+</details>
+
+## Learn more
+
+- [Getting started](docs/getting-started.md) — the full walkthrough, every command
+- [Every agent](docs/agents.md) — install commands and config for 35+ agents
+- [Design](docs/design/layers.md) — one core per machine, a skill per agent, MCP for the rest; and [access](docs/design/access.md) — how access is granted, signed and revoked
+
+**Status:** v0.5. The test suite runs on Linux, macOS and Windows, and every command is
+run end to end on a real machine of each OS in CI — from a script, as an agent runs it,
+and at a real terminal, as you do. Multi-machine fleets (key, password, invite, handover)
+are tested on Linux machines built from scratch.
+
+Issues and pull requests are welcome — `uv run pytest -q` runs the tests. If fleet saved
+you a GPU-hour, a ⭐ helps other people find it.
+
+[MIT](LICENSE)

agents_fleet-0.5.0.dist-info/RECORD

@@ -0,0 +1,59 @@
+fleet/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fleet/__main__.py,sha256=pcWnqKWwe-Zh_hU0-4-VQarnkKz2STKlc7C6BAGhJj0,718
+fleet/cli.py,sha256=FDypkR5zRwG6MgwD7fTTqYcdFKXH8QoLrZok3j35TTs,103354
+fleet/config.py,sha256=D1ZX6T8NjaoKyuAMA20wAWoZdK1ukTBKbHBoBIuVkUs,3901
+fleet/edit.py,sha256=L73Kk8e66_bOAxWQiBlTGu8niqOVWEOa80yU7HK53qw,7652
+fleet/install.py,sha256=ma1yQlVidHBm0HiBerg7WKqPp_jlMMPqv8-X8PY7KvE,19829
+fleet/links.py,sha256=tn3V8Yk4sFOHFCnwb_ibL6zz5zKaS3khGVee7K9XClk,1152
+fleet/mcpserver.py,sha256=sQTeb1E6270H9t79FbML6MknZAjmp3sFOWCtIfjiToE,14650
+fleet/models.py,sha256=GTAPhl7zrDCBZR4o-1QRel-WGBUb-9mIjhhPc89ACnE,7820
+fleet/onboard.py,sha256=n0BllNRcAPc7-A9Y49aFLIrE5JR9J9P0M_NygmB_8ss,7216
+fleet/reconcile.py,sha256=NyWlIksTjNX_g_r0QpEJ97fazq2o5DyJq2_955R_FbY,10805
+fleet/secrets.py,sha256=vAgIqyQGEtrO08D2aYNEZT6QfXYQFaySHershWnPTNk,2069
+fleet/serve.py,sha256=yCec_TzOVdA7l9Uo0Z4I6ILDqMplsYSZPY1bBSsdf0M,9180
+fleet/service.py,sha256=OrR3ShTZ1j1bzDfTtOTgNj00_AQasSHGZ0AEpAaMwwU,17758
+fleet/ui.py,sha256=CrlkNS7RLX0gqYB_JDklVXkDWQgNJgj-Gr0M1GQ0eys,3182
+fleet/agents/__init__.py,sha256=MaYfaDlE8mltM6F9ORs67ISVkFZwNmwMLMq5wrA-Et0,2057
+fleet/agents/clients.py,sha256=ishgW11a5SY30NneGOiV8RZFxD_Riw1w4XYkwwL2JaE,6071
+fleet/agents/docs.py,sha256=Sx3S8j9_n9cLd2MV2zDFtntfAD77ecqAtmQPpwY6mck,11085
+fleet/agents/registry.py,sha256=QUyXLpW91ufFZV6zEmfhI7jxUA6QqHMck-Ziv9-LzBY,15694
+fleet/agents/usage.py,sha256=M90Sr1Sf6ZYgEe2HPhJKo2sEjKA6nwWEffD9KAMNvno,14725
+fleet/ops/__init__.py,sha256=qLpw1D33WFBUGCE03nzVmnSTFZu0Ms5l1_ZkquSPceM,827
+fleet/ops/enrol.py,sha256=c9sRzEBB4j6FL2SfJW8HE_dat7VU7WCng2xjA9x-PMk,10039
+fleet/ops/errors.py,sha256=UPA1He0f8n4ADnuYUnpyHktcX7sY4ib-8IJtdLkKKm0,970
+fleet/ops/firstrun.py,sha256=YHMI_-8bb0wXP9cN-oeIc48b-iYfN-K_2R1bwQd-1RU,5436
+fleet/ops/handover.py,sha256=85CruDtTo5ZyMhH2Ly65XeS_qBr5NWrSaPtWTzS6DLQ,17835
+fleet/ops/identity.py,sha256=5JPjPs18Lceuj-dyZun4MIvbWK5E8nPpDL1uQ02t04o,2689
+fleet/ops/join.py,sha256=MdX3fPjHQlDdJ2PyYJk-2pnPdSfG5QP2bqvprKJUpwk,20792
+fleet/ops/lifecycle.py,sha256=4gu1RlDcvexuD2GJX5XmU2BPmYP8Zulx1iB75zWMZAQ,8920
+fleet/ops/member.py,sha256=E3UawMcHO_P8tOvz08_No4u977QL_ALGTsOZ_v_3BzM,5649
+fleet/ops/migrate.py,sha256=3Wuds8_uc9wV8uFklytcmW_JPDhSigLO34VBn_7UE1A,3814
+fleet/ops/names.py,sha256=_8XzlEbNu4F41372Fh14ViVX2s0uN40J9-wGaoUPpKA,632
+fleet/ops/rows.py,sha256=OFFXqdr4S1EBIs7I5EYSaY_qHbYn0ER1iA6xm4O11Jk,5312
+fleet/ops/sweep.py,sha256=lczAIRq6CgJVSSM2bCI0BV2vf4Yo494N-oyX7m2wl5U,19397
+fleet/ops/sync.py,sha256=n5d44CypxpcyI_A3vI8RrXoe7n98Jyg3848tm4Mrocc,13388
+fleet/probe/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fleet/probe/parse.py,sha256=auJnzACu_bMZny0Y2-dhyN0LmKqvUf_z6h3lHYW3s14,8880
+fleet/probe/runner.py,sha256=pzh7XZDyrqIDn49ifVRQYzpsZFxg2UBnWoG4vey3XFU,19503
+fleet/render/__init__.py,sha256=cboMaOyK6kmAK6I8oCuYWDTwMhlkmtlbADaJvvunrRY,608
+fleet/render/staleness.py,sha256=_zRjqbaU86Hu9ksKFCLEUb0TrG7Pm1l4uSpeWX0ZMQ0,1275
+fleet/render/top.py,sha256=TjJiv-lm1FJQqtnqxUQHhzWYJwcL7fvTx09l5A9vmro,18691
+fleet/render/view.py,sha256=cUzKwfpfonkqU1FGqytwGPrlWtZkVROigxh0HOC8dd8,22158
+fleet/ssh/__init__.py,sha256=XuviBSkS5oTGZ0BFCxw5oxeE6mLEe6Nji_1zEGigOY0,848
+fleet/ssh/auth.py,sha256=vsP2IJRMn-vCpZSR6SjujFbRHbHtyM2VJPXiQ6de-7I,3188
+fleet/ssh/authkeys.py,sha256=fMHgvbDeXEhhVxtO3CMzAAj3Ltj1EE_xJ04LxuFtu-w,10541
+fleet/ssh/cmd.py,sha256=kOY1qYR75hOZ5iurA8L3vRuJcfJwO-SIr3N3xDSI15Y,17956
+fleet/ssh/keys.py,sha256=Ff-Gj12esE-BppS9SafGBx6j_RKXhvjdU78qyrRN_Mc,15477
+fleet/state/__init__.py,sha256=YSY_cpM-UbWkH6Y80QqujYGIefGZszrr7kFPp5eu8oc,1008
+fleet/state/access.py,sha256=QfflWbS-ZnFdNuoHS-fBC0H9qPtMgeXZgUrn3flyzJs,37249
+fleet/state/inventory.py,sha256=GM_0JOC4GyuLegFZ7kVnh6KmedKcF79dhUk1LSCjlxI,14562
+fleet/state/invites.py,sha256=BMUQN6y0kIXvDg3ImFlJ9W7oSOYAEnX3spFsf-Ru2lo,7855
+fleet/state/store.py,sha256=2Je6WAsMuwE2tlyPzjzDohh4xioaLTkDuaxGhuDBGnc,11042
+fleet/state/writes.py,sha256=bCr8NSUR_hZBHx-Zm10ewfCIfhQnctIutBLso2QMFZ4,10801
+fleet/probe/payload.ps1,sha256=_ZPm6ls0pRhY6RxvSiZL4YBtW8Ihhx2KUWuzUJgzA2E,4125
+fleet/probe/payload.sh,sha256=icutxA4SxqKa88iekOnH7eLT-3-o_hk9l15yTGt0m8A,11720
+agents_fleet-0.5.0.dist-info/METADATA,sha256=BVyylRHyzOlJqeemHgWaGinhxZiOjtUh3eNssymqZKg,11708
+agents_fleet-0.5.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agents_fleet-0.5.0.dist-info/entry_points.txt,sha256=YYX5tkHZMV0tl_c17hhMGkZMSYTuzTfo4STfYW0OYEM,71
+agents_fleet-0.5.0.dist-info/licenses/LICENSE,sha256=7BGi71c6Zfu63DGQNGnNnNMOnsw8guNlSUJsvFWWqpc,1066
+agents_fleet-0.5.0.dist-info/RECORD,,

agents_fleet-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agents_fleet-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agents-fleet = fleet.cli:main
+fleet = fleet.cli:main

agents_fleet-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lin Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fleet/__main__.py

@@ -0,0 +1,15 @@
+"""`python -m fleet`, which exists so the center can serve without a console window.
+
+Windows shows a console for any program built against the console subsystem, and the
+`fleet` launcher uv writes is one. `pythonw.exe` is the same interpreter built against
+the GUI subsystem, so a scheduled task that runs `pythonw -m fleet center --listen` gets
+no window at all -- not a hidden one, and not one that flashes on the way past.
+
+`-m` rather than a second console script: uv generates launchers from the entry points
+in pyproject.toml, and asking it for a windowed variant means asking for a packaging
+feature it does not have. The interpreter is already there next to the one in use.
+"""
+
+from .cli import main
+
+main()

fleet/agents/__init__.py

@@ -0,0 +1,36 @@
+"""Teaching agents what fleet is, on whatever surface they read.
+
+**This is the only part of fleet that writes outside fleet's own directories.** That
+sentence governed one module before the split and governs two now -- `docs` writes skill
+files and marker-delimited regions in AGENTS.md, `clients` writes MCP config JSON -- so
+it lives here, where both are in scope.
+
+The rule it implies is the same in both: never touch a byte we did not write. Files we
+fully own are overwritten wholesale; files that belong to the user get a delimited region
+or a single key, and nothing else in them is disturbed.
+
+`registry` is the data table the other two read, and `usage` is the prose they install.
+Supporting a new agent should be a row in `registry`, not a branch anywhere else.
+"""
+
+from __future__ import annotations
+
+from .clients import (apply_mcp, detect_mcp_clients, install_mcp, installed_mcp_clients,
+                      mcp_entry, remove_mcp, stale_mcp_clients, uninstall_mcp)
+from .docs import (BEGIN, END, Change, apply_block, detect_targets, install,
+                   installed_targets, legacy_paths, plan, remove_block, stale_targets,
+                   uninstall)
+from .registry import (AGENTS, BY_NAME, HERMES_CATEGORY, MCP_CLIENTS, TARGETS, Agent,
+                       McpClient, config_command, fleet_command, fleet_executable,
+                       package_version)
+from .usage import agents_block, dist_skill_text, hermes_skill_text, skill_text, stamp
+
+__all__ = [
+    "AGENTS", "BEGIN", "BY_NAME", "END", "HERMES_CATEGORY", "MCP_CLIENTS", "TARGETS",
+    "Agent", "Change", "McpClient", "agents_block", "apply_block", "apply_mcp",
+    "config_command", "detect_mcp_clients", "detect_targets", "dist_skill_text", "fleet_command",
+    "fleet_executable", "hermes_skill_text",
+    "install", "install_mcp", "installed_mcp_clients", "installed_targets",
+    "legacy_paths", "stale_mcp_clients", "stale_targets", "mcp_entry", "package_version", "plan",
+    "remove_block", "remove_mcp", "skill_text", "stamp", "uninstall", "uninstall_mcp",
+]

fleet/agents/clients.py

@@ -0,0 +1,165 @@
+"""Registering fleet with the desktop clients that speak MCP rather than read a file.
+
+The other half of `fleet setup`, and it writes JSON someone else owns -- a client's
+config file, which may hold servers fleet knows nothing about. So it edits one key under
+`mcpServers` and leaves the document otherwise exactly as found, including the keys and
+the formatting.
+
+Same rule as `docs.py`, arrived at from the other direction: never touch a byte we did
+not write.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from ..state.writes import replace_file
+from .registry import MCP_CLIENTS, UVX, Change, fleet_executable
+
+
+def mcp_entry(cmd: str) -> dict:
+    """What we register. `fleet mcp` serves stdio, which is how clients launch a server."""
+    if cmd == UVX:
+        import shutil
+
+        # Absolute when we can: a desktop client's PATH is not a shell's.
+        return {"command": shutil.which("uvx") or "uvx", "args": ["agents-fleet", "mcp"]}
+    return {"command": cmd, "args": ["mcp"]}
+
+
+
+def apply_mcp(existing: str, key: str, cmd: str) -> str:
+    """Add or update our server in a client's config, leaving every other byte alone.
+
+    Same promise as the markdown region, kept a different way: the document is parsed,
+    exactly one key is set, and it is written back. A config we cannot parse is returned
+    untouched -- refusing to guess is the only safe move on a file we did not write and
+    that may hold someone else's tokens.
+    """
+    import json
+
+    try:
+        doc = json.loads(existing) if existing.strip() else {}
+    except json.JSONDecodeError:
+        return existing
+    if not isinstance(doc, dict):
+        return existing
+    servers = doc.get(key)
+    if not isinstance(servers, dict):
+        servers = {}
+    servers["fleet"] = mcp_entry(cmd)
+    doc[key] = servers
+    return json.dumps(doc, indent=2) + "\n"
+
+
+
+def remove_mcp(existing: str, key: str) -> str:
+    """Drop our server. A config that never had one comes back untouched."""
+    import json
+
+    try:
+        doc = json.loads(existing) if existing.strip() else {}
+    except json.JSONDecodeError:
+        return existing
+    if not isinstance(doc, dict) or not isinstance(doc.get(key), dict):
+        return existing
+    if doc[key].pop("fleet", None) is None:
+        return existing
+    return json.dumps(doc, indent=2) + "\n"
+
+
+
+def detect_mcp_clients(root: Path, platform: str = "") -> list[str]:
+    """MCP clients that have actually run here. Judged by the directory their config
+    lives in, because the file itself does not exist until one is configured."""
+    platform = platform or sys.platform
+    out = []
+    for c in MCP_CLIENTS:
+        path = c.path(root, platform)
+        if path and path.parent.is_dir():
+            out.append(c.name)
+    return out
+
+
+
+def installed_mcp_clients(root: Path, platform: str = "") -> list[str]:
+    """Clients that already have fleet registered -- the only ones a refresh touches."""
+    platform = platform or sys.platform
+    out = []
+    for c in MCP_CLIENTS:
+        path = c.path(root, platform)
+        if not path or not path.exists():
+            continue
+        try:
+            doc = json.loads(path.read_text(encoding="utf-8") or "{}")
+        except (OSError, ValueError):
+            continue
+        if isinstance(doc, dict) and isinstance(doc.get(c.key), dict) \
+                and "fleet" in doc[c.key]:
+            out.append(c.name)
+    return out
+
+
+def stale_mcp_clients(root: Path, cmd: str, platform: str = "") -> list[str]:
+    """Registered clients whose entry points somewhere other than this fleet."""
+    platform = platform or sys.platform
+    out = []
+    for c in MCP_CLIENTS:
+        if c.name not in installed_mcp_clients(root, platform):
+            continue
+        path = c.path(root, platform)
+        current = path.read_text(encoding="utf-8")
+        if apply_mcp(current, c.key, cmd) != current:
+            out.append(c.name)
+    return out
+
+
+def install_mcp(root: Path, clients: list[str], cmd: str, *,
+                dry_run: bool = False, platform: str = "") -> list[Change]:
+    """Register `fleet mcp` with each client, without disturbing its other servers."""
+    platform = platform or sys.platform
+    changes: list[Change] = []
+    for client in MCP_CLIENTS:
+        if client.name not in clients:
+            continue
+        path = client.path(root, platform)
+        if path is None:
+            continue
+        current = path.read_text(encoding="utf-8") if path.exists() else ""
+        desired = apply_mcp(current, client.key, cmd)
+        if desired == current and current.strip() and "fleet" not in current:
+            # apply_mcp returns the file untouched when it cannot parse it, which is the
+            # right thing to do to someone else's config and the wrong thing to report
+            # as "unchanged" -- that reads as already set up.
+            changes.append(Change(client.name, path, "unreadable"))
+            continue
+        action = ("unchanged" if desired == current
+                  else "created" if not current else "updated")
+        if action != "unchanged" and not dry_run:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            replace_file(path, desired)
+        changes.append(Change(client.name, path, action))
+    return changes
+
+
+
+def uninstall_mcp(root: Path, clients: list[str], *,
+                  dry_run: bool = False, platform: str = "") -> list[Change]:
+    platform = platform or sys.platform
+    changes: list[Change] = []
+    for client in MCP_CLIENTS:
+        if client.name not in clients:
+            continue
+        path = client.path(root, platform)
+        if path is None or not path.exists():
+            continue
+        current = path.read_text(encoding="utf-8")
+        desired = remove_mcp(current, client.key)
+        action = "removed" if desired != current else "unchanged"
+        if action == "removed" and not dry_run:
+            replace_file(path, desired)
+        changes.append(Change(client.name, path, action))
+    return changes
+