hyperguild/cmd/hyperguild/README.md

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 <type> <slug>

Reads markdown from stdin, writes a knowledge entry.

$ cat <<EOF | hyperguild brain write knowledge example-lesson
# Example lesson

## Lesson
...
EOF
knowledge/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 (default 7d; accepts Nh, 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:

• cloud — brain MCP only. Claude Code with no routing.
• client-local — brain + routing pod. The routing entry points at koala:30310/mcp (the routing pod, deployed in Plan 6). The X-Hyperguild-Mode: client-local header is forward-compat for future modes; the pod treats absent or unknown values as client-local.
• sovereign — brain only, with a _mode_note explaining that this mode primarily uses Crush + LiteLLM and the .mcp.json is 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 spec
• docs/superpowers/plans/2026-05-03-hyperguild-cli.md — implementation plan