6318167e5a
Agents (esp. Pi/Codex) under-use the buried tools index and hand-roll raw `tmux send-keys` / raw `tea`/`gh` instead of the wrappers. Lead the doc with a ~25-line actionable block — #1 inter-agent messaging via tools/tmux/agent-send.sh, #2 git wrappers + the GITEA_LOGIN auto-pick-by-origin-host rule (the GetUserByName-on-USC trap) — and add the missing tmux row to the suites table. Content-only; injected into every runtime prompt via buildRuntimePrompt. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QoYiBeKNh3BiYtAJS5Z587
5.5 KiB
Machine Tools — Index
Tool suites live at ~/.config/mosaic/tools/<suite>/. This is the index only.
Full CLI signatures, flags, and examples: ~/.config/mosaic/guides/TOOLS-REFERENCE.md —
read it (or the relevant service guide) when your task actually touches that service.
Project-specific tooling belongs in the project's AGENTS.md, not here.
⚡ Most-used fleet tools (reach for these FIRST — don't hand-roll)
You are a Mosaic fleet agent. These cover the highest-frequency cross-agent and git-provider
tasks — use them before improvising with raw tmux send-keys, raw tea/gh/glab, or curl.
1. Message another agent → tools/tmux/agent-send.sh (NOT raw tmux send-keys):
tools/tmux/agent-send.sh -s <target-session> -m "message" # or -f <file> to send a file's contents
The coordinator session is mos-claude — send status, findings, and questions there.
2. Issues / PRs / milestones → tools/git/*.sh wrappers (before raw tea/gh/glab):
tools/git/pr-create.sh ... tools/git/issue-create.sh ... tools/git/pr-merge.sh ...
tools/git/ci-queue-wait.sh --purpose push|merge # REQUIRED before any push/merge
GITEA_LOGIN gotcha — the wrappers default to login mosaicstack; on a USC repo that fails with
gitea / Error: GetUserByName ... not found. Pick the login from the repo's origin host first:
| origin host | login |
|---|---|
git.uscllc.com |
export GITEA_LOGIN=usc |
git.mosaicstack.dev |
default mosaicstack (no export needed) |
Suites (use wrappers first)
| Suite | Path | Purpose |
|---|---|---|
| tmux | tools/tmux/agent-send.sh |
inter-agent messaging (see "Most-used" above) |
| git | tools/git/*.sh |
issues, PRs, milestones, CI queue guard (platform-auto-detected) |
| woodpecker | tools/woodpecker/*.sh |
CI pipelines (-a mosaic|usc; match git remote host) |
| portainer | tools/portainer/*.sh |
Docker Swarm stacks (status/redeploy/list) |
| coolify | tools/coolify/*.sh |
DEPRECATED — superseded by Portainer; do not use for new deployments |
| authentik | tools/authentik/*.sh |
identity (users/groups/apps/flows) |
| cloudflare | tools/cloudflare/*.sh |
DNS (zones/records; -a instance) |
| glpi | tools/glpi/*.sh |
IT tickets/computers/users |
| health | tools/health/stack-health.sh |
service health checks |
| codex | tools/codex/*.sh |
code/security review (--uncommitted) |
| openbrain | tools/openbrain/*, tools/openbrain_client.py |
semantic memory (see below) |
| excalidraw | MCP mcp__excalidraw__* |
diagram export/generation |
Git wrappers are MANDATORY-first for issue/PR/milestone ops (see AGENTS.md hard gates 6–8).
Queue guard before push/merge: tools/git/ci-queue-wait.sh --purpose push|merge.
Credentials
source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials <service>
Supported: portainer, coolify (deprecated), authentik, glpi, github, gitea-mosaicstack,
gitea-usc, woodpecker, cloudflare, turbo-cache, openbrain. Never expose or commit values.
OpenBrain — Semantic Memory (PRIMARY) — capture when you LEARN, never when you DO
Primary cross-agent memory (pgvector). Capture decisions/gotchas/preferences/patterns; never task
starts, commits, PRs, test results, or file edits. At session start, search + recent to load
prior context. MCP (mcp__openbrain__capture/search/recent/stats) preferred when connected; else
REST/tools/openbrain_client.py. Full protocol: guides/MEMORY.md.
MANDATORY jarvis-brain rule: when working in ~/src/jarvis-brain, NEVER capture project data,
meeting notes, status, timelines, or task completions to OpenBrain — the flat files
(data/projects/*.json, data/tasks/*.json) are the SSOT (use tools/brain.py + direct JSON
edits). OpenBrain there is for agent meta-observations ONLY (tooling gotchas, framework learnings,
cross-project patterns). Violating this creates duplicate, divergent data.
Git Providers
| Host | Instance | CI |
|---|---|---|
| git.mosaicstack.dev | mosaic (default) | ci.mosaicstack.dev (-a mosaic) |
| git.uscllc.com | usc | ci.uscllc.com (-a usc) |
Match Woodpecker -a and credential instance to the target repo's git remote host.
Safety Defaults
- Prefer
trashoverrmwhen available — recoverable beats gone forever. - Never run destructive commands without explicit instruction.