Superbee

A markdown knowledge bundle in your repo, plus a CLI built for agents.

Coding agents forget everything between sessions, overwrite each other's work, and keep what they know invisible to the humans they work for. Superbee gives them shared, versioned, conflict-safe memory in plain text — offline-first, standards-based, owned by you.

Status: early and experimental. A public npm prerelease is available for testing; formats and commands will change without ceremony, and some of the project's biggest ideas are still bets under test. The honest breakdown is below — read it before depending on anything.

Install

Requirements: macOS or Linux, and Node.js 20 or newer.

The current test release is on npm's next prerelease channel; latest provides the stable release. Install the prerelease with:

npm install -g superbee@next
superbee setup

npm install -g superbee installs the stable channel. The package's optional Agent Skill teaches Claude Code, Codex, and OpenCode how to use the installed command without carrying another copy of the executable. OpenCode uses its documented Claude-compatible Skill discovery, so it shares Claude Code's Skill bytes unless a custom Claude config root requires separate documented host paths.

Bare and host-scoped setup are read-only and agent-friendly: without flags it reports private-state health and lists the four supported hosts; after the agent selects its exact host, it inspects npm, Agent Skill, SessionStart hook, MCP registration, current bundle, and private workspace catalog, then returns one safe next.command. Fill any explicit placeholder it identifies, run the command, restart the named host after integration changes, and rerun the same setup command until the plan is complete. It never guesses a host as permission to edit configuration. After a CLI upgrade, home and SessionStart also report managed Agent Skills whose stale bytes can pass the installer's complete read-only preflight, with the exact refresh command and restart requirement; conflicts stay with explicit setup/status diagnostics and no host files change automatically. If setup returns superbee setup migrate-state, that explicit command copies validated legacy operational records into Superbee's private state root while preserving every legacy byte; it does not move project bundles.

The hook is recommended rather than required: it gives Claude Code, Codex, and OpenCode a compact Superbee orientation at session start. To try read-only and bootstrap commands without installing anything, run npx -y superbee; persistent integrations still require the global npm install.

The npm package is the sole executable distribution channel. The optional Agent Skill contains guidance and references only; it invokes the npm-installed CLI rather than carrying another copy. The new package installs only superbee, so it can coexist with a global @holaxis/aslite long enough for superbee setup to inspect and migrate exact legacy integrations. Once setup is complete, remove the old package with npm uninstall -g @holaxis/aslite; the successor does not keep the retired aslite or agentstate-lite commands on PATH. If upgrading from the retired marketplace plugin, remove or disable that plugin, then rerun superbee setup and follow its exact next command. The hook installer replaces exact historical AgentState marketplace hooks rather than leaving two SessionStart hooks.

Quickstart

superbee                                   # confirm that no bundle is selected yet
superbee recipes                           # compare the workspace setups shipped offline
superbee init --create-only --recipe work-tracking --dir .superbee
superbee new "Task" first-task --title "Plan the first change" --progress_status todo \
  --actor process:quickstart-agent --dir .superbee
superbee --dir .superbee                   # see the Task in the live bundle summary

--create-only refuses an occupied, nested, bound, or concurrently claimed target before it writes; use recipe add when you deliberately want to add capability to an existing bundle. Bring source material or intent to your agent in the tool you already use. The agent organizes, types, links, and updates the bundle through superbee; these commands are the plumbing, not a manual data-entry workflow.

process:quickstart-agent is an advisory example actor identity; replace it with the actual actor identity (human:<id>, process:<id>, or <producer>/<version>).

New Superbee bundles use Open Knowledge Format (OKF) v0.2. Existing OKF v0.1 bundles remain supported without automatic migration.

The conventional .superbee/ folder at the project root is discovered with zero config (the way git finds .git) — every command after setup runs bare from anywhere in the project tree. A bundle stays local until sync --establish explicitly shares it on the repository's dedicated board branch. The remote repository must already exist: Superbee creates and pushes only the board branch, never the GitHub repository that contains it.

Existing .agentstate-lite/ bundles and .agentstate.json bindings continue to work with Superbee; no migration is required. When the first task needs a roadmap, run superbee recipe add roadmap. Before sharing, determine whether the intended remote repository exists, then whether origin/board exists. A confirmed-missing repository is created outside Superbee by an authorized account/organization actor (or by an authorized teammate who then grants access). For an existing repository with no board, repository-creation authority is irrelevant: with explicit consent, repository-specific push capability, and branch-create policy clearance, run superbee sync --establish. If origin/board already exists, join with ordinary superbee sync instead. A failed remote check leaves both facts unknown; diagnose URL, network, HTTPS/SSH identity, visibility, and repository Read access before any establishment attempt. If valid .superbee/ and .agentstate-lite/ bundles exist at the same project level, Superbee reports a conflict and refuses to choose; move the bundle you do not intend to use outside the project before retrying.

When the conventional project folder does not fit:

• Project binding: preferred .superbee.json, with .agentstate.json retained for existing projects. Either is a committed local pointer ({ "bundle": "<path>" }) for an out-of-tree directory and beats the conventional folder. Both names at the same level are a conflict rather than an implicit choice. Remote access is never ambient: pass --remote <url> explicitly. Legacy URL bindings and AGENTSTATE_LITE_REMOTE fail with migration guidance instead of activating HTTP.

• Private workspace: the bundle lives outside the repo (for example, ~/superbee-workspaces/<name>/); a git-excluded binding points at it, and nothing enters the repo.

• Personal catalog: register any local bundle under a user- or agent-defined label so it is visible when an agent starts outside that project. The catalog is explicit and machine-local: it never crawls, clones, or creates an ambient active workspace. Resolve a label to a path, then pass that path to an ordinary command:

  superbee catalog add personal --dir ~/superbee-workspaces/personal
  superbee catalog list
  superbee catalog resolve personal --field path
  

Then, day to day:

export SUPERBEE_ACTOR=process:claude   # optional default; per-command --actor wins
superbee new "Task" ship-parser --title "Ship the parser" --progress_status todo
superbee list --type Task
superbee doc update tasks/ship-parser --progress_status in_progress
superbee doc history tasks/ship-parser # who changed what, when
superbee ui                            # the bundle, rendered — local server, no cloud
superbee index generate                # optional: complete portable Markdown navigation
superbee sync                          # ordinary shared-board updates — commits yours,
                                       # pulls theirs, pushes; leaves code files untouched

init always makes a LOCAL bundle; sync joins or updates a SHARED one, while sync --establish is the one-time, explicit act that turns this project's local bundle into a shared board (a board branch in an already-existing origin repository) — never automatic, so a bare sync never silently publishes a bundle nobody asked to share. Once a board exists (here or on a teammate's clone), plain sync is everyone's setup AND ongoing verb: a fresh clone's first sync provisions the board from origin; a project with a local bundle but no shared board reports its local-only state honestly (changes stay on this machine) and routes to --establish. If origin cannot be checked, sync reports the shared-board state as unknown and waits for a retry instead of recommending publication. When a doc changed on both sides, sync converges: your teammate's version is kept, yours is saved to an export file, and sync --show-incoming <id> + doc update reconcile — no git surgery. Bundles committed directly to a code branch are also supported as the IN-TREE mode: board docs travel with your normal commit/push/pull, sync --pull-only fetches the branch's upstream and reports incoming board changes (session start shows the same awareness), and a full sync refuses with guidance — sync --establish is the explicit conversion to a dedicated board branch.

sync --establish also handles a project that already committed .superbee/ or legacy .agentstate-lite/ to its code branch: it prints a preview first, and --yes executes — publishing the board branch from the folder's current files and preparing a cleanup commit on a side branch that you open as a PR (the folder leaves the code branch; the board takes over after the merge).

Establishment appends both recognized bundle directories (.superbee/ and .agentstate-lite/) to the root working-tree .gitignore and reports that uncommitted edit. Ordinary sync performs the same reported repair when provisioning discovers that either ignore entry is missing.

If you see a board branch in a repo that uses Superbee: that is the shared board — an orphan branch carrying only the knowledge bundle, written by superbee sync. It never merges into main (it shares no history with it, by design). Protect it the way you protect main: enable delete and force-push protection on board in the repo settings — sync only ever appends commits to it.

How it works

Tools that need a small, portable bundle identity can import the versioned JSON Schema and TypeScript contract from superbee/bundle-descriptor. The contract describes a bundle but grants no access or authority; see Bundle Descriptor v1.

• Every concept is a typed markdown document. One required frontmatter field — type — plus whatever fields its schema declares. New concepts are new types, not new subsystems. Byte-exact artifacts such as View HTML live as blobs referenced by those documents.
• Portable navigation is explicit. index generate creates a complete relative-link index.md hierarchy for GitHub, ordinary editors, and copied folders. It refreshes only marked generated files and refuses curated indexes unless --force deliberately adopts them.
• Schemas are documents too. A "kind" is declared by a convention doc inside the bundle; validation fires at write time (warn by default, --strict to reject). The bundle describes itself.
• Schema guidance travels with the data. Kinds can describe the concept itself, individual fields, enum values, and relationship labels; the CLI projects that guidance through kinds and kind-specific new --help output so agents do not need a separate live explanation.
• Relationships are ordinary markdown links with convention-declared semantics. A kind can name and describe allowed outbound link labels and expected inbound relationships; the CLI can warn or lint mismatches and query exact link labels. Backlinks are always derived, never stored.
• Writes are compare-and-swap. Every document state has a content-addressed version; a racing writer gets a typed conflict instead of silently losing an update. Every mutation is attributed.
• Storage is a seam. The engine holds all semantics; filesystem, memory, and wire backends plug in underneath with byte-identical version tokens.
• Recipes install capability as text. A recipe is a folder of definitions, applied idempotently — it seeds schemas and may carry explicitly declared static References and self-contained Views, then the bundle owns them. A definitions-only package rejects instance data and undeclared files. Three recipes ship built-in (context-notes, work-tracking, roadmap); examples/recipes/claims is the minimal custom-Kind example, while examples/recipes/review-workflow is a complete content-free cognitive ecosystem: a self-describing Review Request kind plus a generic live View, with no review instances.

Bundles use Open Knowledge Format v0.2 by default - plain markdown any tool conforming to that edition can read. Existing OKF v0.1 bundles remain supported without rewriting their declared edition.

What's solid

• The engine and the storage seam: a broad suite across four workspaces, with the filesystem, memory, and wire backends pinned to byte-identical version tokens.
• The CLI surface, built agent-first: structured output, counts and truncation with escape hatches, idempotent mutations, a small stable exit-code taxonomy.
• The byte channel (promote/pull) for artifacts that should never enter a model's context window.
• Project discovery: a committed .superbee/ or legacy .agentstate-lite/ folder (or an explicit .superbee.json / supported .agentstate.json binding) resolves the bundle for any agent on any machine with zero prior context.

What's early or experimental

• Everything is pre-1.0. The npm package is a prerelease and breaking changes are likely.
• Native Windows support is separate. The superbee executable supports macOS and Linux. Most Windows users should run Superbee in WSL2. Windows adapters and the superbee-windows executable are developed in a separate repository, https://github.com/Holaxis-ai/superbee-windows-cli, which is open source with build-from-source instructions; it is experimental, unsupported, and not published to npm. See the CLI upgrade guidance and core filesystem migration before upgrading.
• Recipes as composition is a thesis under test, not a result. The repository includes small first-party definitions-only packages, including a Kind-plus-View reference, but package dependencies, upgrades, migrations, and marketplace discovery remain future work. "Cookbooks" (composed recipes with typed-link glue) are design intent only.
• Bundle Views and the local web UI are functional but still early. ui launches registered Views in sandboxed iframes; data Views receive a narrow read-only bridge with live change events, while bundle-propose Views may ask trusted shell chrome to confirm one local, CAS-guarded scalar-field change. Content Views receive no bundle-data capability. Views can navigate to other registered Views, and View-bearing definitions-only recipes can carry the operating model, registry entry, HTML, and authoring reference together. (Page is the legacy name for the kind and is no longer read — a legacy type: Page doc does not register, and the legacy bridge: field grants nothing; superbee status flags leftover legacy names and the repo's migrate-legacy-view-names script renames them in place. Legacy folder locations stay recognized.) Authoring is still HTML/agent-driven rather than a polished end-user builder, so treat the surface as a preview.
• The public package ends at a generic remote boundary. serve exposes a bundle through the versioned wire protocol, and bundle commands can target a service explicitly with --remote. A gated service may accept SUPERBEE_API_KEY (AGENTSTATE_LITE_API_KEY remains supported) or an already-provisioned stored per-origin credential. This repository ships no hosted deployment, identity system, account-administration commands, or cloud-provider package.
• Wire protocol v0.1 is evolving. One recorded caveat: a document's raw bytes re-serialize to canonical form over the wire; blobs are the byte-exact channel.
• Filesystem CAS is serialized across same-user local processes with an external per-target runtime lock. A process crash can leave a diagnosable lock behind; writes fail closed until it is inspected and removed rather than silently stealing an ambiguous lock.
• Richer graph semantics remain open: conventions type outbound links and can require at least one matching inbound relationship today, but richer cardinality, cross-edge constraints, workflow rules, and automation are intentionally not a second graph engine yet.
• OKF itself is young and evolving; we track it as it changes.

Where the deep documentation lives

This project dogfoods itself: the plans, research, design docs, product statement, and the full change history live in the project's own Superbee bundle, which the team develops against daily. The repo also carries three narrow contracts at the boundary where a fresh clone must remain sufficient: the CLI's AXI contract, the implemented wire protocol, and private vulnerability routing in SECURITY.md. Other deep documentation remains in the bundle rather than creating a second manually coordinated product authority.

License

Apache-2.0 © 2026 Holaxis