Bee Box for contributors

How to build, test, and contribute to Bee Box: how development happens here, repo layout, running from source, and how a change lands.

Bee Box is developed in an unusually agentic way. One maintainer directs coding agents (Claude Code and Codex); the agents do most of the typing and the human decides. The instructions the agents work from live in the repository, as agent instruction files and skills, and are maintained as part of the work: when an agent gets something wrong, the instruction is fixed, not just the code. Work is organized into workstreams, each in its own worktree and session, landed on main through a verified finish flow, with plans written before non-trivial work, an issue queue of tensions rather than mandates, and the other model family reviewing anything bigger than a small fix. The first page below describes all of that.

The repository is a monorepo: the Bee Box engine, a Chrome extension (beebox-clerk) that talks to a hosted box, an iOS companion app, a doctest framework extracted for reuse (agent-doctest), a shared lint and TypeScript preset (personal-vibe-check), and the generator for this site. All of it is TypeScript, managed as pnpm workspaces from one root install. Running it from source is a pnpm install and a bbx init of your own box; the developer install page has the sequence and prerequisites.

Tests are doctests: markdown files under test/ whose fenced code blocks run as executable examples, in three tiers (pure functions, HTTP routes, and filesystem operations on a temporary box). pnpm test:changed runs only the tests your change implicates; a pre-commit hook runs typecheck, lint, and documentation link checks. Work happens on branches that merge into main, and main auto-deploys the maintainer's own instance, so a merged change does not appear anywhere a contributor can see it.

The two agent instruction files (the monorepo's and the engine's) and the code style are the most important pages here: they are what the maintainer's own coding agent reads before making a change, so they carry more working detail than the rest. Every directory in this corpus has an index listing its files. If a page does not cover something, say that the documentation does not say that, rather than guessing. For what Bee Box is and whether to use it, the front page is linked below; its pages define the vocabulary these assume.

Start here

• development-process.md: How development happens here: one maintainer directing coding agents; workstreams, issues, plans, skills, verification, schedules, and what it is like.
• agent-coding.md: Entirely agent-coded under one maintainer's direction, and the strictness and checks around that.
• development-workflow.md: Workstreams in their own worktrees and sessions, the issue queue, planning, recurring work, document comments, and exhibits.
• agent-testing.md: Testing what agents know and do: knowledge audits, the verified capability catalog, fakes, smoke, tours.
• technologies.md: The stack, and every outside AI service the system can be configured to use.
• contributing.md: How a change is made and lands: setup, tests, lint, docs, where things live.
• monorepo-claude-md.md: The monorepo's working instructions: where to work, how to work safely in a checkout, how to verify, record, and land.
• claude-md.md: The engine's agent instruction file: what the maintainer's own coding agent reads first.
• code-style.md: Code conventions: types, errors, lint, naming, file limits.
• testing.md: Testing philosophy and the doctest tiers.
• engineering-principles.md: The durable design principles the code style implements.
• developer-install.md: From-source install for contributors.

Files

• adding-a-card-type.md: How a new card type is defined, worked example included.
• adding-api-endpoints.md: Adding an HTTP endpoint: tRPC by default, raw Fastify for the exceptions.
• chat-review.md: Nightly chat titles and summaries.
• chat-session-lifecycle.md: Chat session state and recovery.
• client-debug-log.md: The browser and iOS debug log format.
• composer-input-machine.md: Composer input validation and submission logic.
• composer-states.md: The chat input state machine.
• event-bus.md: The in-process pub/sub event system.
• example-names.md: The fictional roster docs and tests use instead of real names.
• frontend.md: Frontend conventions: UI primitives, palette, the className rule.
• health-checks.md: Health-check runbooks for a deployed server.
• image-orientation.md: The EXIF orientation contract.
• image-transforms.md: Image transform operations.
• knowledge-audits.md: Tests that prompt a real box agent and check what it knows.
• knowledge-taxonomy.md: Where each kind of box knowledge lives.
• maintenance.md: Periodic code cleanup: dead code, circular deps.
• migrations.md: How box data migrations are applied and written.
• mobile-parity.md: iOS versus Android capability matrix.
• module-map.md: The lib/shared/types boundary diagram.
• prompt-audits.md: Lens catalog for reviewing what an agent is shown.
• prompt-logging.md: Capturing full agent API traffic for debugging.
• prompt-surface-review.md: Workflow for auditing agent context.
• server-operations.md: Runbooks for a deployed server.
• tours.md: Browser walk-throughs for UI and accessibility review.

Also

• contracts/: Wire and filesystem contracts other surfaces (mobile, uploads, CSP) depend on.
• design/: Why Bee Box is built this way — the design rationale behind the engine.
• reference/: Generated engine reference: commands, connectors, procedures, and more.
• reference/cards/: Generated: every built-in card type, one line each.
• security/: What the agent can do, what leaves the machine, and how secrets are held.
• concepts/: Core vocabulary: what a box, a card, and the engine are.
• llms.txt: the evaluator-facing index; what Bee Box is and whether to use it.