vh
53c3e8000e
Every agent on nh3-dev — Claude, Codex, Grok, Aider — needs the same answers: what runs here, how do I call it, what will bite me. Until now that lived in ~/.claude/CLAUDE.md, which only Claude sessions load, and it was interleaved with operator preferences that other families have no use for. Two-tier by design, matching the persistent-memory split: FLEETTOOLS.md is a 135-line index an agent reads whole, and each entry links to a detail file it opens only when it actually needs that tool. Reading the index costs about a fifth of reading the tree. Detail paths are absolute so they resolve from any working directory, since a non-Claude agent will cat the path rather than follow a markdown link. ~/FLEETTOOLS.md symlinks to the index for discovery. Rule zero is that live inventories get queried, not transcribed: Homepage /api/services, asset-engine /api/v1/services, LiteLLM /v1/models, and every FastAPI seat's /openapi.json. A copied service table would be stale within a month and this repo already has a standing rule against second copies that drift. Contents verified against the running fleet rather than copied from existing docs: binaries resolved on PATH, seven endpoints probed live, the LiteLLM roster counted at 40 models where the old note said ~30. No credentials are included; the vault and its CLI are pointed at instead.
1.4 KiB
1.4 KiB
elway — SSH playbook runner (CHANGING things)
Path: ~/development/eshpfi-management/scripts/elway (not on PATH)
scripts/elway <host> --playbook playbooks/<name>.yaml
Write a playbook under playbooks/ instead of chaining ssh -t host 'sudo …'.
Handles sudo once lazily, gives structured pass/change/fail reporting, supports
idempotency via creates: / when: / changed_when:, and does file upload.
Template: ~/development/eshpfi-management/playbooks/elway-smoke.yaml
The split — pick by what you are doing
| tool | why | |
|---|---|---|
| CHANGING something | scripts/elway |
idempotency, sudo handling, file transfer, structured results |
| LOOKING at something | remote-ssh MCP (Claude) or plain ssh |
no ceremony; a persistent shell where cd and exports survive |
Neither replaces the other. Reconnaissance — the docker ps / grep / curl
questions — does not warrant authoring a playbook.
Traps
- Deploys must converge, not accrete. The staging directory must be OUTSIDE the rsync target; inside, it becomes a silently frozen source. Verify CONTENT, not liveness.
pkill -f <pattern>over ssh kills your own shell when the pattern matches your own argv (exit 255). Kill by explicit PID or pidfile.- Never run destructive fs operations on a variable path.
rm/shred/mv-over take LITERAL paths, one per line. No loops, no variables.