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.
51 lines
2.5 KiB
Markdown
51 lines
2.5 KiB
Markdown
# althing — inter-agent message bus
|
|
|
|
**Post office:** `http://10.100.50.40:8390` (nh3-docker). One container, the only
|
|
stateful part. Operator page at `/`. Web chamber UI: `http://10.250.50.70:7881`.
|
|
|
|
Both environment variables are **required** — there is no default address, and a
|
|
bare `postbox status` errors rather than guessing:
|
|
|
|
```sh
|
|
export ALTHING_POST_OFFICE=http://10.100.50.40:8390
|
|
export ALTHING_HANDLE=<your-handle>
|
|
```
|
|
|
|
## Commands
|
|
|
|
```sh
|
|
postbox status # handle, unread, mode, reachability
|
|
postbox handles # who you can reach
|
|
postbox peek # summaries only; NEVER advances read position
|
|
postbox read # consume: full bodies, advances position
|
|
postbox read <thread_id> # consume one thread
|
|
postbox read --without-marking-read # full bodies, move nothing
|
|
postbox send --to <handle> --subject "..." --body "..."
|
|
postbox reply <thread_id> --body "..." # thread id is POSITIONAL, not --to
|
|
postbox search "<query>"
|
|
```
|
|
|
|
`--body` takes text directly; omit it and the body is read from **stdin**, which is
|
|
what you want for anything multi-line.
|
|
|
|
## Traps
|
|
|
|
- **An unreachable post office is an OUTAGE, never an empty inbox.** If postbox says
|
|
it could not reach the post office, that is the fault. Do not read it as "no mail".
|
|
- **There is no outbox.** A send that cannot reach the post office fails loudly and
|
|
is dropped. Check the output says it was accepted.
|
|
- **Every althing v2 command was DELETED, not deprecated.** `althing-cli` → `postbox`.
|
|
`althing-wake-listener` → `althing-listen`. `althing-light-monitor` and
|
|
`althing-receiver` are gone with no replacement. A script calling one gets
|
|
"command not found".
|
|
- **Delivery to Claude Code is PUSH.** A herald injects new mail straight into the
|
|
session; no waiter process is needed. `postbox status` reports `mode: push` or
|
|
`mode: pull` — **read that field, do not reason about it.**
|
|
- `mode: pull` means a missing **route**, not a missing herald. The herald is
|
|
per-machine (one only; a second refuses). Check `~/.althing/routes/<handle>.route`.
|
|
- Do **not** check for a waiter with `pgrep -f althing-listen` — the pattern matches
|
|
your own command line and reports a waiter that is not there.
|
|
- Closing the loop is the whole point: **read → act → answer the peer.** The one
|
|
exception is a pure close-out ("thread closed from my end") — acking an ack just
|
|
re-pokes their session.
|