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
88 lines
5.5 KiB
Markdown
88 lines
5.5 KiB
Markdown
# 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`):
|
||
|
||
```bash
|
||
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`):
|
||
|
||
```bash
|
||
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 `trash` over `rm` when available — recoverable beats gone forever.
|
||
- Never run destructive commands without explicit instruction.
|