mathiasandClaude Sonnet 5
975b61c9d7
PR #131 removed WriteNote's legacy brain/knowledge/ fallback branch that activated when wing/hall were both empty, but never updated the CLI that was the only caller relying on it. Since `hyperguild brain write` never sent wing/hall, every invocation of the CLI's most load-bearing brain command started hard-erroring "wing and hall are required" — a live, README-documented command broken on every call. Separately, writeRequest never had a `slug` field (pre-existing, unrelated to #131): the CLI's slug value was silently dropped server-side even before this PR, falling back to a timestamp filename. Fix: - `hyperguild brain write <wing> <hall> <slug>` replaces the old `<type> <slug>` shape. Positional args, mirroring the existing `brain query <topic>` pattern and matching writeHallNote's own wing/hall/slug parameter order server-side (handler.go's brain.NotePath(brainDir, wing, hall, slug)) — no new flags needed since wing/hall/slug are all required, not optional filters. - brainClient.Write now sends {wing, hall, filename, content}, matching writeRequest exactly (writeRequest already gained a Filename field in #131, so no server-side change was needed — only the CLI was sending the wrong shape). This also fixes the dead slug bug: slug now arrives server-side as filename instead of being silently dropped. - Added TestWrite_CLIPayloadRoundTrips in ingestion/internal/api, which POSTs the CLI's exact JSON envelope to the real Handler.Write (not a mock) and asserts a real file with real wing/hall frontmatter lands on disk. cmd/hyperguild and ingestion are separate Go modules (no go.work), so this can't be a single cross-module test — instead the wire contract is pinned from the server side, closing the gap where cmd/hyperguild/http_test.go's TestBrainClient_Write_Success used only a hand-rolled httptest mock and stayed green through the wing/hall regression. - Updated cmd/hyperguild/README.md and the 2026-05-03 CLI design spec's stale `<type> <slug>` examples. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
hyperguild CLI
A small Go binary for tier probing, brain HTTP REST access, and
.mcp.json mode bootstrap. Replaces the supervisor's tier MCP and
gives shell scripts a stable interface to the brain.
Install
task hyperguild:install
# or: go install ./cmd/hyperguild
The binary lands at $(go env GOBIN)/hyperguild (typically
~/go/bin/hyperguild). Make sure that's on your PATH.
Subcommands
hyperguild tier
Probes Anthropic and LiteLLM and reports the current operating tier.
$ hyperguild tier
tier 1 (full-online) managed_agents=true
$ hyperguild tier --json
{
"tier": 1,
"label": "full-online",
"available_models": null,
"managed_agents": true
}
Probe URLs are read from environment:
| Var | Default |
|---|---|
ANTHROPIC_PROBE_URL |
https://api.anthropic.com |
LITELLM_BASE_URL |
(empty → falls through to airplane) |
hyperguild brain query <topic>
BM25 search over the brain's knowledge + wiki entries.
$ hyperguild brain query "find -H symlink"
knowledge/2026-05-03-find-h-not-l-symlinked-root.md score=12 Use find -H, not find -L
...
Flags:
--limit N— max results (default 5)--json— emit the raw response envelope
hyperguild brain write <wing> <hall> <slug>
Reads markdown from stdin, writes it to brain/wiki/<wing>/<hall>/<slug>.md
with wing/hall/created_at frontmatter injected (there is no legacy
brain/knowledge/ fallback — ADR-0012 / #79, both wing and hall are
required).
$ cat <<EOF | hyperguild brain write homelab facts example-lesson
# Example lesson
## Lesson
...
EOF
wiki/homelab/facts/example-lesson.md
hyperguild brain pass-rate <skill>
Returns the pass rate for a skill over a lookback window. Computed
on-demand from brain/sessions/*.jsonl.
$ hyperguild brain pass-rate tdd
tdd: 47 / 50 = 94% (window: 7d)
$ hyperguild brain pass-rate tdd --window 30d --json
{
"skill": "tdd",
"window": "30d",
"pass": 142,
"fail": 8,
"skip": 5,
"total": 155,
"pass_rate": 0.9467
}
Flags:
--window— lookback window (default7d; acceptsNh,Nd)--json— emit the raw response envelope
Skills with no logged invocations return zero counts and pass_rate: null
(indicating "no data", distinct from "always passes").
hyperguild mode <cloud|client-local|sovereign>
Writes a .mcp.json template for the chosen operating mode.
$ hyperguild mode cloud --out ./.mcp.json
wrote ./.mcp.json (mode: cloud)
Flags:
--out PATH— output file (default./.mcp.json)--force— overwrite an existing file
Modes (all list brain + gitea — Gitea is the audit-trail invariant of the consolidated single harness, #75):
- cloud — brain + gitea MCP.
- client-local — brain + gitea MCP. (The former
routingentry pointing atkoala:30310/mcpwas removed — the routing pod is iceboxed, #75.) - sovereign — brain + gitea, with a
_mode_noteexplaining that this mode primarily uses Crush + LiteLLM and the.mcp.jsonis a Claude Code fallback for emergency offline use.
Environment
| Var | Default | Used by |
|---|---|---|
BRAIN_URL |
http://koala:30330 |
brain *, mode * |
ANTHROPIC_PROBE_URL |
https://api.anthropic.com |
tier |
LITELLM_BASE_URL |
(empty) | tier |
Override BRAIN_URL if your brain pod is at a different Tailscale name
or port.
See also
docs/superpowers/specs/2026-05-03-hyperguild-cli-design.md— full specdocs/superpowers/plans/2026-05-03-hyperguild-cli.md— implementation plan