hive-control

name	hive-control
description	Use when operating, configuring, auditing, or publishing an owner-consented AI laptop control plane: local terminal/files/browser/desktop control, messaging gateways, outbound relays, remote worker lanes, readiness canaries, and public-safe documentation.
version	1.0.0
author	Travis Curnutte
license	MIT
metadata	{"hermes":{"tags":["hive-control","computer-control","relay","gateway","macos","wsl","automation","security"],"related_skills":["hermes-agent","outbound-relay","pantheon-ide-debugging","shell-command-automation","github-repo-management"]}}

HiveControl

Overview

HiveControl is the operating procedure for an owner-approved AI agent that can work on a real laptop. It covers local tools, browser/desktop automation, messaging gateways, outbound relay control, remote worker lanes, verification canaries, and public-safe packaging.

The skill's bias is simple: prove live capability before using it. Memory can say a machine has a relay, a gateway, or full access, but the agent must verify the current system with tools before claiming the route works.

When to Use

Use this skill when the user asks you to:

• control or audit their laptop
• run local terminal/files/browser/desktop tasks
• configure Hermes for mobile or Discord/Telegram control
• inspect or repair a relay/gateway/remote worker lane
• decide whether a remote machine should appear in a swarm
• publish the hive-control pattern as a public GitHub skill/project
• harden a personal AI control plane

Do not use this skill as permission to act outside the user's current request. It explains how to operate verified capabilities; it does not override user scope, safety rules, or platform policy.

Core Principles

1. Owner consent first. The control plane exists because the owner intentionally grants access.
2. Live state beats memory. Always check the actual machine for OS, processes, files, ports, services, and time-sensitive facts.
3. Transport is not execution. Relay status or ACKs do not prove commands ran. Require shell output, file proof, or an exact Hermes canary.
4. Degrade honestly. If a remote lane is offline, clamp capacity and continue local-only instead of pretending the lane exists.
5. Keep public docs sanitized. Do not publish tokens, private hostnames, local auth values, relay URLs, private paths, or user-specific operational details.
6. Leave an audit trail. For non-trivial work, log what changed, what was verified, and what remains degraded.

Capability Discovery Sequence

Run only the checks relevant to the task, but keep this order when diagnosing a full control plane.

1. Local identity and OS

date
uname -a
whoami
pwd

Use terminal tools for current facts. Never answer OS/time/process/ports from memory.

2. Hermes health

hermes doctor
hermes config check
hermes tools list
hermes gateway status

If Hermes is not on PATH, locate it with the user's known install path or shell profile, then verify with an exact command.

3. Local automation surfaces

Check only the surfaces required for the task:

• file operations: target path exists, permissions, git status
• terminal operations: command availability and versions
• browser operations: page loads, DOM state, console errors
• desktop automation: OS permissions for screen recording/accessibility if needed
• messaging: gateway connected and a real platform canary succeeds

4. Services and supervision

On macOS:

launchctl list | grep -E 'hermes|relay|gateway|pantheon'

On Linux/WSL:

systemctl --user --type=service --state=running | grep -E 'hermes|relay|gateway|pantheon'

A service listed as loaded is not enough. Check logs and run a canary through the service path.

Local Laptop Operations

File edits

1. Inspect the target file with read_file.
2. Use patch for targeted edits or write_file for full new files.
3. Run syntax/tests.
4. Re-read or run a verification command.
5. Summarize only the files touched by this task.

Git work

Before changing a repo:

git status --short
git branch --show-current
git rev-parse --short HEAD

Do not overwrite unrelated dirty work. If the repo is already dirty, patch only the requested paths and report the pre-existing dirty state separately.

Browser and UI work

Use browser tools when a visual or runtime condition matters. A correct UI fix should usually verify:

• page loads
• DOM state matches expected labels/counts
• browser console has no new JS errors
• screenshot/vision confirms visible layout when visual styling matters

Desktop automation

Desktop automation is OS- and permission-dependent. Treat it as best-effort until proven. Use visible confirmation or app state as proof, not just a command exit code.

Messaging Gateway Control

Use gateways for owner-controlled mobile/chat access.

Production checklist:

• owner allowlist configured
• message-content/intents enabled where required
• platform command tested from the actual client
• high-risk slash commands are deterministic direct runners when possible
• terminal/relay commands return stdout, stderr, and exit code
• logs redact tokens

Gateway success means a real inbound message or slash command produced a real response. Command sync alone is not enough.

Outbound Relay Pattern

Use a relay for machines behind NAT, on a different network, or inside WSL2.

controlled machine -> outbound WebSocket -> relay hub <- owner/client

Relay connections must authenticate as type: "auth". Client connections authenticate as type: "client_auth". If a machine uses client_auth, it can appear authenticated but will not be counted as a relay.

Relay readiness proof

A remote lane is ready only after all of these pass:

1. status shows expected relay ID online.
2. platform-info returns real remote platform fields.
3. shell returns an exact stdout token.
4. shell can write and read a proof file if filesystem access is required.
5. hermes returns an exact response token if remote AI work is required.
6. service supervision confirms it can survive restarts/sleep where relevant.

Example canaries, replacing <RELAY_CLIENT> with your relay client command:

<RELAY_CLIENT> <relay-id> status
<RELAY_CLIENT> <relay-id> platform
<RELAY_CLIENT> <relay-id> shell 'printf REMOTE_SHELL_OK'
<RELAY_CLIENT> <relay-id> hermes 'Reply exactly: REMOTE_HERMES_OK'

If shell fails but status works, report the remote as connected but not executable. If Hermes fails but shell works, report the relay as executable but remote Hermes unhealthy.

Remote Worker Lanes

Remote workers are useful, but should not silently become co-owners of the local laptop.

Good default assignments:

• research
• review
• Windows/WSL validation
• long-running smoke tests
• artifact generation under a remote temp path

Avoid unless explicitly leased:

• editing local Mac repos
• changing shared memory/skills directly
• restarting local services from remote
• claiming local artifact completion without Mac-side verification

A good remote-worker instruction includes:

You are a remote worker lane. Do not edit the owner laptop's repo or shared skills. Write artifacts under a remote temp directory and return exact paths plus a summary. Mac/local orchestrator verifies before marking done.

Capacity and Swarm UI Rules

If this skill is used with a swarm UI, display usable capacity, not configured fantasy capacity.

• If the remote relay is live and can execute, show remote slots.
• If the remote relay is configured but offline, hide or zero the remote slots.
• Clamp default swarm count to the live capacity.
• Manual remote selection should either fall back safely or report a structured unavailable state.
• Role planning should not mention remote lanes while remote capacity is zero.

Public Documentation Sanitization

Before publishing a hive-control repo, run a sanitization pass.

Remove or replace:

• API keys and bearer tokens
• Discord/Telegram/Slack tokens
• relay auth tokens
• exact private relay URLs
• local bearer values
• private hostnames
• private IPs unless they are documentation-only examples from reserved ranges
• personal paths that are not needed by public users
• screenshots with notifications or private content

Use placeholders:

<CONTROL_AUTH_TOKEN>
<RELAY_URL>
<RELAY_ID>
<OWNER_USER_ID>
<PROJECT_PATH>

Common Pitfalls

1. Saying "I can talk to remote Hermes" because Tailscale ping works. Tailscale proves network reachability only. It does not prove a relay bridge or Hermes subprocess is running.

2. Trusting relay ACKs. {ok: true, note: received} proves only that a bridge received a message. It does not prove shell/Hermes execution.

3. Forgetting the relay auth type. A worker bridge must authenticate as auth, not client_auth, or it will not appear as a relay.

4. Publishing private operational notes. Public GitHub docs should teach the architecture with placeholders, not expose a working personal control plane.

5. Letting remote lanes edit shared state. Remote workers should propose changes or write artifacts. The orchestrator applies protected changes after review.

6. Skipping UI verification. For browser/desktop changes, tests can pass while the visual surface remains wrong. Use DOM and screenshot checks.

7. Assuming service restarts loaded code. After a restart, run the exact endpoint or canary that proves the new path is live.

Verification Checklist

• Live local OS/user/time checked when relevant.
• Target repo status/branch/diff inspected before edits.
• Required local tools/services are verified by command output.
• Browser UI changes are checked via DOM/console and screenshot if visual.
• Relay status includes expected relay ID before remote work.
• Remote shell/Hermes canaries pass before remote execution is claimed.
• Remote capacity is hidden/clamped when the relay is offline.
• Public docs contain placeholders, not secrets or private host values.
• Memory/skill/log updates are made after non-trivial work.

One-Shot Recipes

Full local readiness report

Load hive-control. Check this machine's current local control readiness: OS, Hermes health, enabled tools, gateway status, relevant services, and any degraded routes. Redact secrets.

Remote relay diagnosis

Load hive-control. Diagnose why relay <RELAY_ID> is not usable. Check relay status, target presence, platform canary, shell canary, Hermes canary, service hints, and explain the first failing layer.

Public release cleanup

Load hive-control. Audit this repo for public GitHub release: scan docs/templates/scripts for secrets/private hostnames/private paths, validate skill frontmatter, run tests, and return a publish checklist.