house-council-client

What this does in one paragraph

This is the "house council client bootstrap": a small set of PowerShell scripts that wire a house PC's Claude Code install into the two local-LLM open council MCP servers running on other machines in the house - the gaming PC (RTX 4090, fast GPU models) and the streaming PC (94GB RAM, heavyweight CPU models). Run one script per council on each PC and it registers the MCP server with Claude Code and drops in a matching skill so Claude knows when and how to consult those local models for second opinions, cross-model verification, and code-review votes. Tokens are read from the environment (or a vault), never baked into the scripts.

Why register by an IPv4 literal (the IPv6 rationale)

The council servers listen on IPv4 only. The .local / bare hostname resolves its AAAA (IPv6) record first, so every HTTP request to the hostname eats a ~3s connect timeout before the OS falls back to IPv4 - roughly 2.9s per call instead of ~0.006s. The connect scripts therefore resolve the host's current IPv4 via mDNS at run time and register that literal address with Claude Code, so every MCP call is instant.

DHCP-churn self-heal

The IPv4 address is a DHCP lease, so it can change. There is nothing baked in permanently: each script re-resolves the current IPv4 every time it runs. If a council MCP starts showing "Failed to connect", the fix is simply to re-run the connect script - it discovers the new lease and re-registers the current address.

Pre-flight: SSID (AlphaPhiAlpha vs NSBE)

The house PCs are only reachable on the AlphaPhiAlpha* Wi-Fi. On the NSBE network (172.16.0.x, an isolated island) the other house PCs are unreachable - that is a network segment problem, not a server problem. Before assuming a council is down, check the SSID:

netsh wlan show interfaces | findstr SSID

If you are on NSBE, switch Wi-Fi to AlphaPhiAlpha and try again.

Usage

Set the token for the council you are connecting (get it from the council server config or your KeePass vault - see the Security section), then run the matching script:

# Gaming PC council
$env:COUNCIL_GAMING_TOKEN = "<token>"
pwsh -File scripts/connect-gaming-pc-council.ps1

# Streaming PC council
$env:COUNCIL_STREAMING_TOKEN = "<token>"
pwsh -File scripts/connect-streaming-pc-council.ps1

Windows PowerShell 5.1 works too:

powershell -ExecutionPolicy Bypass -File scripts\connect-gaming-pc-council.ps1

Restart your Claude Code sessions afterward to pick up the new MCP server and skill.

Diagnosing a broken streaming-PC connection

scripts/Test-StreamingCouncil.ps1 is a hermetic connectivity probe (hostname resolution, TCP port checks on the MCP + Ollama ports, an Ollama model-list check, and an optional -Scan subnet sweep for when DHCP has moved the box):

pwsh -File scripts/Test-StreamingCouncil.ps1 -Scan

Repository layout

scripts/   connect-gaming-pc-council.ps1, connect-streaming-pc-council.ps1, Test-StreamingCouncil.ps1
skills/    gaming-pc-council.md, streaming-pc-council.md  (the skills the connect scripts install)
tests/     Council.Tests.ps1, ConnectE2E.Tests.ps1, Invoke-CI.ps1  (Pester 5, hermetic)
archive/   superseded scripts, kept for history (never deleted; secrets scrubbed). Do NOT run.
TESTING.md the full testing matrix (unit + coverage + churn + E2E; why Stryker is N/A here)

Never-delete / archive policy

Superseded files are never deleted - they move to archive/ with a history-encoding filename (...CURRENT-<date>.STALE-<date>.superseded-by-<reason>.ps1) and a header block explaining what replaced them and why. Any secrets in an archived file are scrubbed the same as in live files (real tokens live only in the vault / server config).

Security

• Tokens are never hardcoded. Each connect script reads its bearer token from an environment variable (COUNCIL_GAMING_TOKEN / COUNCIL_STREAMING_TOKEN) or the -Token parameter, and exits with an error if it is unset. The real values live in the council server config and the KeePass vault.
• .env is gitignored; only .env.example (empty placeholders) is committed.
• CI runs a Pester test that fails the build if a council_ token literal ever appears in the scripts, plus a Semgrep scan.
• If you ever need to rotate a token, change it on the council server and in the vault - no code change is required here.