{
  "markdown": "<img src=\"assets/superbee-mark-256.png\" alt=\"\" width=\"96\" height=\"96\">\n\n# Superbee\n\n> A markdown knowledge bundle in your repo, plus a CLI built for agents.\n\nCoding agents forget everything between sessions, overwrite each other's work, and keep\nwhat they know invisible to the humans they work for. Superbee gives them\nshared, versioned, conflict-safe memory in plain text — offline-first, standards-based,\nowned by you.\n\n**Status: early and experimental.** A public npm prerelease is available for testing; formats and\ncommands will change without ceremony, and some of the project's biggest ideas are still bets\nunder test. The honest breakdown is below — read it before depending on anything.\n\n## Install\n\n**Requirements: macOS, Linux, or native Windows, and Node.js 20 or newer.** Windows does not need\nWSL, Ubuntu, or Docker.\n\nThe Windows-capable test release is currently on npm's `next` prerelease channel; `latest` still\npoints to the older stable package that rejects Windows. Install the prerelease with:\n\n```sh\nnpm install -g superbee@next\nsuperbee setup\n```\n\nOn Windows, npm exposes the same command through `superbee.cmd`, which can be invoked explicitly\nwhen PowerShell blocks its `.ps1` wrapper. On macOS or Linux, `npm install -g superbee` remains the\nstable-channel install. The package's optional Agent Skill teaches Claude Code, Codex, and OpenCode\nhow to use the installed command without carrying another copy of the executable. OpenCode uses\nits documented Claude-compatible Skill discovery, so it shares Claude Code's Skill bytes unless a\ncustom Claude config root requires separate documented host paths.\n\nBare and host-scoped `setup` are read-only and agent-friendly: without flags it reports private-state\nhealth and lists the four supported hosts; after the agent selects its exact host, it inspects npm,\nAgent Skill, SessionStart hook, MCP registration,\ncurrent bundle, and private workspace catalog, then returns one safe `next.command`. Fill any\nexplicit placeholder it identifies, run the command, restart the named host after integration\nchanges, and rerun the same setup command until the plan is complete. It never guesses a host as\npermission to edit configuration.\nAfter a CLI upgrade, `home` and SessionStart also report managed Agent Skills whose stale bytes can\npass the installer's complete read-only preflight, with the exact refresh command and restart\nrequirement; conflicts stay with explicit setup/status diagnostics and no host files change automatically.\nIf setup returns `superbee setup migrate-state`, that explicit command copies validated legacy\noperational records into Superbee's private state root while preserving every legacy byte; it does\nnot move project bundles.\n\nThe hook is recommended rather than required: it gives Claude Code, Codex, and OpenCode a compact\nSuperbee orientation at session start. To try read-only and bootstrap commands without installing\nanything, run `npx -y superbee`; persistent integrations still require the global npm install.\n\nThe npm package is the sole executable distribution channel. The optional Agent Skill contains\nguidance and references only; it invokes the npm-installed CLI rather than carrying another copy.\nThe new package installs only `superbee`, so it can coexist with a global `@holaxis/aslite` long\nenough for `superbee setup` to inspect and migrate exact legacy integrations. Once setup is\ncomplete, remove the old package with `npm uninstall -g @holaxis/aslite`; the successor does not\nkeep the retired `aslite` or `agentstate-lite` commands on `PATH`.\nIf upgrading from the retired marketplace plugin, remove or disable that plugin, then rerun\n`superbee setup` and follow its exact next command. The hook installer\nreplaces exact historical AgentState marketplace hooks rather than leaving two SessionStart hooks.\n\n## Quickstart\n\n```sh\nsuperbee                                   # confirm that no bundle is selected yet\nsuperbee recipes                           # compare the workspace setups shipped offline\nsuperbee init --create-only --recipe work-tracking --dir .superbee\nsuperbee new \"Task\" first-task --title \"Plan the first change\" --progress_status todo \\\n  --actor process:quickstart-agent --dir .superbee\nsuperbee --dir .superbee                   # see the Task in the live bundle summary\n```\n\n`--create-only` refuses an occupied, nested, bound, or concurrently claimed target before it\nwrites; use `recipe add` when you deliberately want to add capability to an existing bundle.\nBring source material or intent to your agent in the tool you already use. The agent organizes,\ntypes, links, and updates the bundle through `superbee`; these commands are the plumbing, not a\nmanual data-entry workflow.\n\n`process:quickstart-agent` is an advisory example actor identity; replace it with the actual actor\nidentity (`human:<id>`, `process:<id>`, or `<producer>/<version>`).\n\nNew bundles use Superbee's current portable format automatically. Existing older bundles remain\nsupported in place; Superbee detects their declared format and applies compatibility behavior\nwithout requiring an ordinary-use migration.\n\nThe conventional `.superbee/` folder at the project root is discovered with zero\nconfig (the way git finds `.git`) — every command after setup runs bare from anywhere in\nthe project tree. A bundle stays local until `sync --establish` explicitly shares it on the\nrepository's dedicated `board` branch. The remote repository must already exist: Superbee creates\nand pushes only the `board` branch, never the GitHub repository that contains it.\n\nExisting `.agentstate-lite/` bundles and `.agentstate.json` bindings continue to work with\nSuperbee; no migration is required. When the first task needs a roadmap, run\n`superbee recipe add roadmap`. Before sharing, determine whether the intended remote repository\nexists, then whether `origin/board` exists. A confirmed-missing repository is created outside\nSuperbee by an authorized account/organization actor (or by an authorized teammate who then grants\naccess). For an existing repository with no `board`, repository-creation authority is irrelevant:\nwith explicit consent, repository-specific push capability, and branch-create policy clearance,\nrun `superbee sync --establish`. If `origin/board` already exists, join with ordinary\n`superbee sync` instead. A failed remote check leaves both facts unknown; diagnose URL, network,\nHTTPS/SSH identity, visibility, and repository Read access before any establishment attempt.\nIf valid `.superbee/` and `.agentstate-lite/` bundles exist at the same project level, Superbee\nreports a conflict and refuses to choose; move the bundle you do not intend to use outside the\nproject before retrying.\n\n**When the conventional project folder does not fit:**\n\n- **Project binding:** preferred `.superbee.json`, with `.agentstate.json` retained for existing\n  projects. Either is a committed local pointer (`{ \"bundle\": \"<path>\" }`) for an out-of-tree\n  directory and beats the conventional folder. Both names at the same level are a conflict rather\n  than an implicit choice. Remote access is never\n  ambient: pass `--remote <url>` explicitly. Legacy URL bindings and `AGENTSTATE_LITE_REMOTE`\n  fail with migration guidance instead of activating HTTP.\n- **Private workspace:** the bundle lives outside the repo (for example,\n  `~/superbee-workspaces/<name>/`); a git-excluded binding points at it, and nothing enters the repo.\n- **Personal catalog:** register any local bundle under a user- or agent-defined label so it is\n  visible when an agent starts outside that project. The catalog is explicit and machine-local:\n  it never crawls, clones, or creates an ambient active workspace. Resolve a label to a path, then\n  pass that path to an ordinary command:\n\n  ```sh\n  superbee catalog add personal --dir ~/superbee-workspaces/personal\n  superbee catalog list\n  superbee catalog resolve personal --field path\n  ```\n\nThen, day to day:\n\n```sh\nexport SUPERBEE_ACTOR=process:claude   # optional default; per-command --actor wins\nsuperbee new \"Task\" ship-parser --title \"Ship the parser\" --progress_status todo\nsuperbee list --type Task\nsuperbee doc update tasks/ship-parser --progress_status in_progress\nsuperbee doc history tasks/ship-parser # who changed what, when\nsuperbee ui                            # the bundle, rendered — local server, no cloud\nsuperbee index generate                # optional: complete portable Markdown navigation\nsuperbee sync                          # ordinary shared-board updates — commits yours,\n                                       # pulls theirs, pushes; leaves code files untouched\n```\n\n`init` always makes a LOCAL bundle; `sync` joins or updates a SHARED one, while\n`sync --establish` is the one-time, explicit act that turns this project's local bundle into a\nshared board (a `board` branch in an already-existing `origin` repository) — never automatic, so\na bare `sync` never silently publishes a bundle nobody asked to share. Once a board\nexists (here or on a teammate's clone), plain `sync` is everyone's setup AND ongoing verb:\na fresh clone's first `sync` provisions the board from origin; a project with a local\nbundle but no shared board reports its local-only state honestly (changes stay on this\nmachine) and routes to `--establish`. If origin cannot be checked, sync reports the\nshared-board state as unknown and waits for a retry instead of recommending publication.\nWhen a doc changed on both sides, sync\nconverges: your teammate's version is kept, yours is saved to an export file, and\n`sync --show-incoming <id>` + `doc update` reconcile — no git surgery. Bundles committed\ndirectly to a code branch are also supported as the IN-TREE mode: board docs travel with\nyour normal commit/push/pull, `sync --pull-only` fetches the branch's upstream and reports\nincoming board changes (session start shows the same awareness), and a full `sync` refuses\nwith guidance — `sync --establish` is the explicit conversion to a dedicated board branch.\n\n`sync --establish` also handles a project that already committed `.superbee/` or legacy\n`.agentstate-lite/` to\nits code branch: it prints a preview first, and `--yes` executes — publishing the board\nbranch from the folder's current files and preparing a cleanup commit on a side branch\nthat you open as a PR (the folder leaves the code branch; the board takes over after the\nmerge).\n\nEstablishment appends both recognized bundle directories (`.superbee/` and `.agentstate-lite/`) to\nthe root working-tree `.gitignore` and reports that uncommitted edit. Ordinary sync performs the\nsame reported repair when provisioning discovers that either ignore entry is missing.\n\n**If you see a `board` branch** in a repo that uses Superbee: that is the shared\nboard — an orphan branch carrying only the knowledge bundle, written by `superbee sync`. It\nnever merges into `main` (it shares no history with it, by design). Protect it the way\nyou protect `main`: enable delete and force-push protection on `board` in the repo\nsettings — sync only ever appends commits to it.\n\n## How it works\n\nTools that need a small, portable bundle identity can import the versioned JSON Schema and\nTypeScript contract from `superbee/bundle-descriptor`. The contract describes a bundle but grants\nno access or authority; see\n[Bundle Descriptor v1](https://github.com/Holaxis-ai/superbee/blob/main/packages/bundle-descriptor/README.md).\n\n- **Every concept is a typed markdown document.** One required frontmatter field — `type` — plus\n  whatever fields its schema declares. New concepts are new types, not new subsystems. Byte-exact\n  artifacts such as View HTML live as blobs referenced by those documents.\n- **Portable navigation is explicit.** `index generate` creates a complete relative-link\n  `index.md` hierarchy for GitHub, ordinary editors, and copied folders. It refreshes only marked\n  generated files and refuses curated indexes unless `--force` deliberately adopts them.\n- **Schemas are documents too.** A \"kind\" is declared by a convention doc inside the\n  bundle; validation fires at write time (warn by default, `--strict` to reject). The\n  bundle describes itself.\n- **Schema guidance travels with the data.** Kinds can describe the concept itself, individual\n  fields, enum values, and relationship labels; the CLI projects that guidance through `kinds`\n  and kind-specific `new --help` output so agents do not need a separate live explanation.\n- **Relationships are ordinary markdown links with convention-declared semantics.** A kind can\n  name and describe allowed outbound link labels and expected inbound relationships; the CLI can\n  warn or lint mismatches and query exact link labels. Backlinks are always derived, never stored.\n- **Writes are compare-and-swap.** Every document state has a content-addressed\n  version; a racing writer gets a typed conflict instead of silently losing an update.\n  Every mutation is attributed.\n- **Storage is a seam.** The engine holds all semantics; filesystem, memory, and wire\n  backends plug in underneath with byte-identical version tokens.\n- **Recipes install capability as text.** A recipe is a folder of definitions, applied\n  idempotently — it seeds schemas and may carry explicitly declared static References and\n  self-contained Views, then the bundle owns them. A `definitions-only` package rejects instance\n  data and undeclared files. Three\n  recipes ship built-in (`context-notes`, `work-tracking`, `roadmap`);\n  `examples/recipes/claims` is the minimal custom-Kind example, while\n  `examples/recipes/review-workflow` is a complete content-free cognitive ecosystem: a\n  self-describing Review Request kind plus a generic live View, with no review instances.\n\nBundles are valid [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)\n— plain markdown any conformant tool can read. Superbee writes the current format for new bundles\nand preserves existing legacy bundles without rewriting their declared edition.\n\n## What's solid\n\n- The engine and the storage seam: a broad suite across four workspaces, with the\n  filesystem, memory, and wire backends pinned to byte-identical version tokens.\n- The CLI surface, built agent-first: structured output, counts and truncation with\n  escape hatches, idempotent mutations, a small stable exit-code taxonomy.\n- The byte channel (`promote`/`pull`) for artifacts that should never enter a model's\n  context window.\n- Project discovery: a committed `.superbee/` or legacy `.agentstate-lite/` folder (or an explicit `.superbee.json` /\n  supported `.agentstate.json` binding) resolves the bundle for any agent on any machine with zero\n  prior context.\n\n## What's early or experimental\n\n- **Everything is pre-1.0.** The npm package is a prerelease and breaking changes are likely.\n- **Windows uses native policy rather than POSIX mode emulation.** Per-user operational state lives\n  under `%LOCALAPPDATA%`, whose ACL boundary is the Windows containment authority. The required\n  Windows CI lane runs every workspace suite on Node 22 and installs and exercises the packed npm\n  artifact on Node 20. WSL2 remains a Linux environment and is not a substitute for that native\n  Windows coverage.\n- **Recipes as composition** is a thesis under test, not a result. The repository includes\n  small first-party definitions-only packages, including a Kind-plus-View reference, but package\n  dependencies, upgrades, migrations, and marketplace discovery remain future work. \"Cookbooks\"\n  (composed recipes with typed-link glue) are design intent only.\n- **Bundle Views and the local web UI** are functional but still early. `ui` launches registered\n  Views in sandboxed iframes; data Views receive a narrow read-only bridge with live change events,\n  while `bundle-propose` Views may ask trusted shell chrome to confirm one local, CAS-guarded\n  scalar-field change. Content Views receive no bundle-data capability. Views can navigate to other registered\n  Views, and View-bearing definitions-only recipes can carry the operating model, registry entry,\n  HTML, and authoring reference together. (`Page` is the legacy name for the kind and is no\n  longer read — a legacy `type: Page` doc does not register, and the legacy `bridge:` field\n  grants nothing; `superbee status` flags leftover legacy names and the repo's\n  `migrate-legacy-view-names` script renames them in place. Legacy folder locations stay\n  recognized.) Authoring is still HTML/agent-driven rather than a\n  polished end-user builder, so treat the surface as a preview.\n- **The public package ends at a generic remote boundary.** `serve` exposes a bundle through the\n  versioned wire protocol, and bundle commands can target a service explicitly with `--remote`.\n  A gated service may accept `SUPERBEE_API_KEY` (`AGENTSTATE_LITE_API_KEY` remains supported) or an already-provisioned stored per-origin\n  credential. This repository ships no hosted deployment, identity system, account-administration\n  commands, or cloud-provider package.\n- **Wire protocol v0.1** is evolving. One recorded caveat: a document's raw bytes\n  re-serialize to canonical form over the wire; blobs are the byte-exact channel.\n- **Filesystem CAS is serialized across same-user local processes** with an external per-target runtime lock.\n  A process crash can leave a diagnosable lock behind; writes fail closed until it is inspected\n  and removed rather than silently stealing an ambiguous lock.\n- **Richer graph semantics** remain open: conventions type outbound links and can require at least\n  one matching inbound relationship today, but richer cardinality, cross-edge constraints,\n  workflow rules, and automation are intentionally not a second graph engine yet.\n- OKF itself is young and evolving; we track it as it changes.\n\n## Where the deep documentation lives\n\nThis project dogfoods itself: the plans, research, design docs, product statement, and\nthe full change history live in the project's own Superbee bundle, which the\nteam develops against daily. The repo also carries three narrow contracts at the boundary where a\nfresh clone must remain sufficient: the CLI's [AXI contract](packages/cli/AXI-CONTRACT.md), the\nimplemented [wire protocol](docs/WIRE-PROTOCOL.md), and private vulnerability routing in\n[SECURITY.md](SECURITY.md). Other deep documentation remains in the bundle rather than creating a\nsecond manually coordinated product authority.\n\n## License\n\nApache-2.0 © 2026 Holaxis\n",
  "bytes": 18449,
  "sha": "583840552b2848675a9a1fa6fb1000f6413bbe08730166fc03809c95bca2cb7a",
  "repo_slug": "holaxis-ai/superbee",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_holaxis_ai_superbee_cognition_skills_sup_6abc4df8/readme"
}