GitHub login required for advisory posting

### Sign in with GitHub

Enter this code on GitHub to authorize Hive:

--------
Open GitHub →
Waiting for authorization...

### GitHub App Setup Required

Hive needs a GitHub App to authenticate. Choose an option:

#### Use the public Hive App (quickest)

Dashboard login only. Agents can read repos but cannot create issues, PRs, or merge.

#### Create your own GitHub App (recommended for full ACMM)

Full agent capabilities: issues, PRs, auto-merge. Required for ACMM levels 3-6.

Quick setup:

1. Open `hive.yaml` on the host (mounted at `/etc/hive/hive.yaml` inside the container)
2. Add to the `github:` section:
   `oauth_client_id: Ov23ligE2p0gjXg6xAUf`
3. Restart the container: `docker compose restart hive`
4. Click "Sign in with GitHub" again

Create a GitHub App:

1. Go to github.com/settings/apps/new (or your org's Settings → Developer settings → GitHub Apps)
2. Set the app name (e.g. `my-hive`)
3. Homepage URL: any URL (e.g. `https://github.com/kubestellar/hive`)
4. Uncheck "Webhook → Active" (not needed)
5. Under "Device Flow", check Enable Device Flow
6. Set the permissions below, then click "Create GitHub App"
7. On the app page, note the App ID and Client ID
8. Generate a private key (.pem file) and save it to `./secrets/gh-app-key.pem`
9. Install the app on your org/repos. If the app's Setup URL is set to this hive's `/gh-setup` URL, finishing the install in the same browser configures the Installation ID automatically; otherwise note the Installation ID from the URL after install.
10. Update `hive.yaml`:

    github:
      app_id: <your-app-id>
      installation_id: <your-installation-id>
      key_file: /secrets/gh-app-key.pem
      oauth_client_id: <your-client-id>

Restart the container after updating.

##### Required Permissions (Repository)

- Contents: Read & write (clone, push branches)
- Issues: Read & write (create/close issues)
- Pull requests: Read & write (create/merge PRs)
- Metadata: Read-only (required by GitHub)
- Checks: Read-only (monitor CI status)
- Actions: Read-only (monitor workflow runs)

##### Required Permissions (Organization)

- Members: Read-only (identify contributors)

🐝 Hive Chat

##

## ACMM Maturity Level

Select your AI-native Continuous Maturity Model (ACMM) level. Each level provides a curated set of agents with increasing autonomy. Agents are additive — higher levels build on lower ones.

## 🐝 Getting Started

GitHub API authentication failed. Check GitHub App key or token configuration.
● live

# 🐝 KubeStellar Hive Dashboard for KubeStellar/Console
⬇ Widget

⚠️
GitHub App Not Installed
This hive cannot create issues or advisory reports. Install the Hive Hub GitHub App on your repository; this hive checks every few minutes and will configure itself, or you can paste the Installation ID below.
Install GitHub App
⚠️
Repo Target Misconfigured
Expected org/repo.

## ▼ 📋 Advisory Digest

## ▼ Repositories

## ▼ Beads

## ▼ 🎯 ACMM Evaluation

--
Codebase Readiness
--
Operational Autonomy
--
Overall ACMM
--
Criteria Passed
Repo:

## ▼ 📋 Audit Log

Loading audit log...

## ▼ 🧪 Strategy Lab

## ▼ 💡 Project Inception

## ▼ 📚 Knowledge Base

▼

## 👥 Contributors

Share /contribute link → 🏆 Leaderboard

## ▼ 🔍 System Diagnostics

## ▼ 📋 Agent Logs

Follow

## ▼ Agents

## ▼ ❓ FAQ

Common questions from first-time users. Everything below describes what this hive actually does today — where behaviour is surprising, it is called out rather than smoothed over.

### What is the Advisory Digest for?

The Advisory Digest is the work ledger. It is the collection of beads your agents open — the running record of what the hive has found and what it would act on, if you let it. Agents create each bead with `bd create`; the digest rolls up every open bead of type `advisory`, `bug`, or `feature`, grouped by the agent that filed it. Internal agent work items (`task`, `decision`) are deliberately excluded so the ledger stays readable.

You can read the same ledger in two places. Here in the dashboard, and in GitHub: the hive opens a single issue titled 🐝 Hive Advisory Report in your default repo and keeps a digest comment on it up to date each cycle. That issue is the whole of the hive's GitHub footprint at Level 2 — reading it in GitHub means the ledger lands where your normal workflow already lives.

### What do the colors mean?

The colored bar on the left of each finding, and its dot, encode severity, which is derived directly from the priority the agent set on the bead (`--priority 0` through `3`):

- 🔴 critical (priority 0) — red bar
- 🟠 high (priority 1) — orange bar
- 🟡 medium (priority 2) — yellow bar
- 🔵 low (priority 3) — grey bar
- ⚪ info — anything else; grey bar

Note the icon and the bar disagree slightly at the bottom end: low shows a blue dot but a grey bar, since only critical/high/medium have dedicated bar colors. Severity is set by the agent that filed the bead, using the priority rubric in that agent's policy — it is a judgement call, not a measurement.

### How are digest items selected and ordered?

They are not ranked by severity. This is the single most common misreading of the digest. Findings are grouped by agent (agents sorted alphabetically), and within each agent they appear in the order the beads were created — oldest first, chronologically. Severity is a label you can scan for; it has no effect on position. A critical finding filed this morning sits below a low-severity one filed last week. So: read the whole of an agent's group, or scan for 🔴/🟠, but do not assume the top of the list is the most important thing. Selection is simply "every open advisory/bug/feature bead" — there is no cutoff or scoring. Beads closed in the last 48 hours appear separately as recently resolved.

### What am I supposed to do with it?

Level 2 is a trust level. It exists to show you how Hive works, what it would find, and how it might fix it — if you let it. So the job at L2 is not to fix everything in the ledger. It is to decide whether you believe the ledger.

The intended way to do that: point your own agent — `claude` CLI, `bob` shell, `copilot` CLI, running on your own laptop — at the 🐝 Hive Advisory Report issue, and have it read the findings and suss out whether they make sense. You are reviewing the hive's judgement using a tool you already control, on a repo the hive cannot write to. That is the whole point of the level.

Alongside that:

1. Skim for 🔴 and 🟠 first, since ordering will not surface them for you (see below).
2. For anything you agree with and want tracked, open a real GitHub issue yourself — at L2 the agents cannot.
3. A large ledger on a first run is normal. It is the accumulated backlog of a codebase nobody has audited before, not a list of new problems, and not a queue you are expected to burn down.

### How do I move from L2 to L3?

Change to L3 whenever you like — there is no gate. No quota, no checklist, no criteria that must go green first. The only criterion is your own judgement: do you trust the advisory findings you have been reading? That is what L2 is for. Once you believe the beads, you are ready.

What changes: at L2 (Advisory (Instructed)) the only thing the hive touches in GitHub is its own 🐝 Hive Advisory Report issue. L3 (Quality-Gated (Measured)) introduces the quality agent, and its job is building test cases — making your repo resilient to code changes from any contributor that would destabilise it, break it, or violate patterns you prefer. That is the next step in gaining trust: not more findings, but a safety net. Concretely, the quality agent may open GitHub issues and hold-gated pull requests that add test coverage. "Hold-gated" means every PR is opened with a `hold` label, and the agent is forbidden from merging it or removing that label — so a human merges every change, always. L3 is deliberately scoped to tests only: no production code, no refactors, no features. The point of L3 is to build the test coverage that makes the more automated levels above it safe.

Why this is the pivotal level. Test coverage is the critical safeguard that makes every later level defensible. Agents opening issues and PRs on their own (L4–L5), and eventually auto-merging them (L6), are only safe once there are tests that can catch a bad change. So the ACMM ladder is not a feature ladder you climb for more capability — each level earns the trust that makes the next one safe. L3 is where you build the net that the automation above it falls into.

Optional aid, not a gate: the ACMM Eval page scores your repo against per-level criteria and reports a Codebase Readiness level. It is useful for seeing where your test and CI scaffolding currently stands, and Criteria Passed will show you which checks fail. But nothing there blocks or licenses a level change — you can move to L3 with readiness reading L1. Treat it as information, not permission.

How to actually change it: use the ACMM badge in the sidebar, or the Change level ▾ button on the ACMM Eval section. Both open the same dialog. It offers two distinct actions, and the difference matters: Preview only changes what this dashboard displays and leaves running agents untouched, while Apply is the real move — it creates the agents in that level's pack, resumes them, and pauses agents not in the pack. Do not edit `hive.yaml` by hand to change level; the dialog is the supported path.

### What about L4, L5, L6?

Each level hands over more of the acting, and each is only safe because of the level below it. The end-to-end journey: L2 shows you what Hive would find; L3 builds the safety net that makes acting on those findings safe; L4–L6 progressively hand over more of the acting. Nothing is fully autonomous until L6:

- L1 — Inception (Assisted) — advisory only; typically used to start a new feature with tools like speckit.
- L2 — Advisory (Instructed) — the trust level. Advisory beads only; the sole GitHub write is the 🐝 Hive Advisory Report issue and its digest comment.
- L3 — Quality-Gated (Measured) — introduces the quality agent: hold-gated test-coverage PRs, CI gates. The safeguard everything above depends on.
- L4 — Security-Aware (Adaptive) — agents open issues, plus a security-check agent. Still not autonomous: issues and PRs remain hold-gated for human review.
- L5 — Semi-Autonomous (Semi-Automated) — PRs carry a hold label, reviewed in batches.
- L6 — Fully Autonomous — auto-merge once CI is green.

L4 and above become available after provisioning; newly created hives start in the L1–L3 range.

### My spend jumped after I raised my ACMM level. How do I manage cost?

First, the honest framing: higher levels increase throughput and spend, and that is the design, not a malfunction. A hive that merges ~60 PRs in an afternoon burned tokens roughly in proportion to the work it did. If the PRs were good, that spend bought something. The lever you want is usually not "spend less per unit of work" but "do less work per day" — and that lever is cadence.

Seven things you can actually turn, roughly in order of effect:

1. Widen your agent cadences — the primary lever. Cadence is the interval between governor kicks, set per agent per governor mode. The Governor panel shows this as a grid — agents down the side, the four modes (idle / quiet / busy / surge) across the top, plus method and model columns. Click any row (or the config gear on that agent's dashboard card) to adjust its cadences. Going from `1h` to `6h` is roughly a 6× cut in that agent's kick count, and `12h` or `24h` cuts further. Because the value is per mode, the highest-value edit is usually widening busy and surge — those are the modes a high ACMM level spends most of its time in.
   Units are `m` and `h`. Write one day as `24h`, not `1D`. A day suffix is not valid in `hive.yaml` — the governor parses cadences with Go's duration parser, which rejects `1d`/`1D` outright, and an unparseable cadence is skipped with a log warning, leaving that agent with no schedule at all rather than a slow one. `0` disables the agent in that mode.
2. Pause agents you are not using. Each agent card on the Agents page has a ⏸ pause button — a paused agent is never kicked by the governor until you resume it. You can also set a mode's cadence to `0` to switch an agent off in just that mode, which is a scalpel where pausing is a hammer.
3. Set a real budget. Governor Config → Budget → Total Tokens is the cap (`0` disables budget tracking entirely). The enforcement that actually bites is kick suppression: a soft warning fires at 90% of the limit, and at 100% the governor stops kicking agents until the window rolls. Per-Agent Exemptions lets chosen agents keep running through an exhausted budget.
   Three caveats before you lean on this. The budget is denominated in tokens, not dollars, so it will not line up one-to-one with a provider's billing page. The accounting window is a fixed 7 days and the warning fires at a fixed 90% — the Period (days) and Critical Percent fields are stored but do not currently change that behaviour, so treat the window as weekly regardless of what they say. And the governor panel's ignore budget checkbox disables enforcement entirely, so check that it is unticked.
4. Move work onto cheaper agents. Two independent dials on each agent card: the model picker (higher tiers such as Opus cost more per token than Sonnet or Haiku) and the method picker (the CLI or inference backend). Notably copilot and goose are treated as free backends and do not count toward the token budget at all. Routine, high-frequency agents are the best candidates to move down; leave the agents whose judgement you actually depend on where they are. Both columns also appear in the Governor panel's grid, with a 📌 pin next to each to lock in a method or model you deliberately chose.
5. Re-check the level itself. If the spend is not buying PRs you actually merge, the level — not the cadence — is the wrong setting. Dropping from L5 to L4 or L3 is a legitimate cost control, and the ACMM dialog moves in both directions.
6. Move inference off metered APIs entirely. Two options change the cost model rather than trimming it. Self-hosted models — point agents at vLLM or llm-d via the method picker, and per-token API charges become fixed infrastructure you already run. Donated compute — ClankeR, the contributor relay, hands tasks from your hive's backlog to CLI agents running on contributors' machines, on their credentials, which never leave their machine. Contributors start rate-limited and auto-promote as tasks complete.
   If you move to vLLM or llm-d, revisit the next item: self-hosted models are exactly the case where the supervisor earns its keep.

And one more that is easy to miss, because it is on by default and you did not choose it:

7. Turn the supervisor off if you are on `claude`, `copilot`, `bob`, or `litellm`. The supervisor's core job is watching the other agents' tmux panes for ones stuck at a prompt — waiting on a human instead of running to completion. That failure mode is now predominantly a self-hosted inference problem: open-source models served via vLLM or llm-d need an injected preamble telling them to never ask for permission and never stop, precisely because they otherwise stop and ask. Frontier CLI agents are explicitly unaffected by that preamble, and `litellm` opts out of it too, on the grounds that it usually fronts frontier models. CLI agents used to stall this way; in practice they no longer do. If you are running only CLI backends or litellm, the supervisor is mostly watching for a condition that no longer occurs — and it is not free: the shipped packs kick it every `5m` in most modes (every `1m` at L6), which is the tightest cadence of any agent.
   Keep it if you run vLLM or llm-d agents — that is the case it was built for, and it is the direct trade-off against the self-hosted option above: moving inference in-house cuts your token bill but reintroduces the stalling behaviour the supervisor exists to catch. It is also doing secondary work — spotting idle, crashed, and rate-limited agents — so on a mixed fleet, widening its cadence is the safer move than switching it off outright.

Why it is on in the first place, and how to turn it off. The supervisor ships enabled in every default pack from L2 to L6 (on `copilot`), so you will find it running even though you never asked for it. That default dates from when CLI agents genuinely did stall; it has outlived the problem. Turning it off is therefore a deliberate act.

Note that the supervisor's agent card has no ⏸ pause button — it is suppressed for this one agent, so the usual route does not work and it can look undisableable. It is not. Use the Governor panel's cadence grid: click the supervisor row to open its Cadences tab and set the modes you want silenced to `pause` (or `0`). This is a supported, first-class value — the shipped L3 and L4 packs already use `supervisor: pause` for idle mode — and the governor applies it to the supervisor with no special-casing. The equivalent edit in `hive.yaml` is the same key under each mode's `cadences:` block.

Finally, some perspective: model pricing has been falling steadily, and cheap models keep getting more capable. Other hives are already running successfully on low-cost models, so today's bill for a given amount of work is not a fixed property of the system.

### How does cadence impact cost? My scanner seems to run non-stop.

Cadence is the wait between runs, not a limit on how long a run lasts. This is the single most common misunderstanding about cost, so it is worth stating plainly. An agent session does not go on forever: the agent works until it runs out of work, then stops. Cadence is how long Hive waits after that before kicking it again.

Which means a busy agent can look like it is running continuously, and effectively be running continuously — without anything being wrong. If your scanner faces a large queue (say, issues that other agents have been opening), each session has plenty to chew on, so it runs long, finishes, and gets kicked again shortly after. Shortening cadence does not make an agent work harder; widening cadence spreads the same work over more wall-clock time, which is exactly what lowers the burn rate.

There is a second, less obvious effect worth knowing. The governor picks its mode from the count of actionable open issues — cross a threshold and it escalates idle → quiet → busy → surge, and every agent switches to that mode's (shorter) cadence column. So a growing backlog raises spend on its own, without you changing any setting. Working the backlog down lowers the mode, and the mode drives the pace. The thresholds themselves are editable under Governor Config → Thresholds.

Two cadence values in the grid are not durations. paused means the governor never kicks that agent until you resume it. on demand means the agent is only ever kicked manually — it has no automatic schedule at all.

### Is the first day supposed to cost this much?

Yes, and it is the least representative day you will have. Budget for a day-one spike, then expect it to fall. Pointing a hive at an existing repo for the first time is the single most expensive thing you will ask it to do, because a mature codebase carries years of accumulated technical debt that nobody has triaged — and the scanner finds essentially all of it at once.

That produces enough queued work to keep agents busy continuously, which is exactly what "running non-stop" looks like. It is not a runaway loop; it is a real backlog being worked. One early adopter saw ~60 PRs in an afternoon — small, targeted ones — at roughly five minutes of agent work apiece, which is about five hours of genuine output. The bill tracked the work.

Two things compound on day one, and both unwind on their own:

- The backlog is at its deepest, so agents rarely run out of work and stop early — sessions run long.
- A deep backlog of actionable issues pushes the governor into busy or surge, which is the mode column with the shortest cadences. So the pace goes up at precisely the moment there is most to do.

As the backlog drains, both effects reverse: agents finish their queue and sit idle until the next kick, and the governor settles back toward quiet or idle with its longer intervals. Steady-state cost is materially lower than onboarding cost, so extrapolating your first day into a monthly figure will overestimate — usually by a lot.

If you would rather not absorb the spike all at once, the levers above still apply on day one — start at a lower ACMM level, widen cadences before the first run, or set a Total Tokens budget so the spike is capped. Draining the initial backlog is a one-time cost, and paying it more slowly is a legitimate choice.

### Where did the money actually go?

The 💵 Cost section is the place to look. It reports an estimated total — token counts multiplied by a dated list-price table — with a timeframe selector offering hourly, daily, weekly, monthly, and custom ranges, so you can line a spike up against what the fleet was doing at the time. Each agent card also shows a spend figure attributed to that agent over whichever timeframe the Cost section is set to, which is how you find the one agent responsible for a jump.

Treat it as an estimate, not a bill. It is derived from token counts and list prices, so a subscription plan, a discounted rate, or self-hosted inference will all diverge from it — and models without an exact price entry fall back to a coarse tier estimate (shown with a `~`). It is the right tool for attribution — which agent, which model, which day — rather than for reconciling against an invoice. The per-agent figure is also derived from a cumulative counter, so it can read blank for a window that spans a restart.

To see what an agent was asked to do, open that agent's Prior Prompts tab — each kick is recorded with its timestamp and the fully expanded prompt text, with a Window selector offering Last hour, Last day, and Last week. The 📋 Audit Log is the other half: it records that a kick, start, or restart happened and what triggered it.

What you cannot currently see is time. Nothing records how long a past session ran, so there is no way to confirm "it ran flat out for four hours" from the UI — and no per-run cost figure either, since spend is bucketed by time rather than attributed to individual kicks. The nearest proxy is Last Run on an agent card, which is when the governor last kicked it, not how long it worked. Agent output is a live 500-line tmux buffer that is lost on restart, so it cannot be used to reconstruct older activity.

### Why couldn't the Guide agent answer my questions?

Because the guide agent documents your project, not Hive itself. Its job is to audit your repo's README, getting-started, architecture and contributing docs and report the gaps — at L1–L2 as beads and an issue, at L3+ as doc PRs. It is explicitly barred from writing code, filing triage issues, or reviewing PRs, and it has no special knowledge of Hive's own workflow or ACMM levels. Questions about how to operate your hive belong here, not to an agent.

### A first week, end to end

1. Start at L1–L2. Let the agents run a full cycle against your repos and populate the ledger.
2. Read the ledger on the Advisory page, or on the 🐝 Hive Advisory Report issue in your default repo. Expect it to be long. Scan for 🔴/🟠 rather than reading top-down.
3. Audit it with your own agent. Point `claude`, `bob`, or `copilot` on your laptop at that issue and ask whether the findings hold up. This is the core L2 activity — you are calibrating whether the hive's judgement matches yours.
4. Act on a handful. File real issues for the findings you agree with; ignore the rest.
5. Advance to L3 when you trust the findings — that judgement is the only prerequisite. Use the ACMM dialog and choose Apply (not Preview). Optionally glance at ACMM Eval first for context on where your test and CI scaffolding stands.
6. Review the first hold-gated PRs. They will be test-coverage PRs from the quality agent. Merging them is a manual step, by design — and the coverage they add is what makes L4+ safe to turn on.