CONTRIBUTING.md is the authority on process: if the two disagree, CONTRIBUTING.md and the root package.json win. Why the code is shaped the way it is lives in the contributor overview.
Before you begin
- Node.js 22.13 or later and pnpm 9. The root
package.jsondeclaresengines.node >=22.13.0andengines.pnpm >=9.0.0, and pinspnpm@9.15.0as its package manager. ESLint 10 and parts of the test toolchain need 22.13; the publishedclawbooCLI still runs on 22.12. - No external runtime. Clawboo Native runs agents inside the server, with a provider key or a local Ollama. Install OpenClaw, Claude Code, Codex or Hermes only when you work on that runtime.
Make a change
1
Clone and install
corepack enable makes pnpm the pinned 9.15.0, which keeps lockfile diffs clean. pnpm install links the whole workspace: packages/*, packages/adapters/*, apps/* and docs (see Monorepo and build).2
Run the dev stack
- The Vite SPA serves on port 5173.
- The API takes the first free port from 18790 to 18809. Pin it with
CLAWBOO_API_PORT(see Environment variables). pnpm devalso starts the docs preview (mint dev --port 3111), which needs the Mintlify CLI.
~/.clawboo/, created on first run. Set CLAWBOO_HOME to point a dev instance at a throwaway directory. There are no feature flags: every subsystem is on. Budgets track spend and warn, and nothing pauses a run until someone sets a hard cap.3
Work on a branch
Clawboo follows GitHub Flow: branch from
main, push, open a pull request, and squash-merge once CI is green. Name the branch with a prefix:4
Run the local gate
These are the checks CI runs, as root scripts:
pnpm format:checkruns Prettier; fix failures withpnpm format. CI’s Lint job runs it beforepnpm lint.pnpm lintruns ESLint across the workspace, the docs frontmatter and heading check, andscripts/.pnpm testruns every package’s Vitest suites, includingapps/web’s node project (*.test.ts) and jsdom project (*.test.tsx, with React Testing Library, msw, jest-dom and jest-axe). CI runs the same suites aspnpm test:coverage, which adds a coverage table and no threshold.pnpm e2eruns Playwright in a sandboxed$HOME. It needspnpm buildfirst and a Chromium download (pnpm exec playwright install chromium).pnpm catalog:verifychecks every marketplace content rule, then thatcatalog/distand the compiled seed match a rebuild.pnpm verify:connectorschecks the committed connector catalog. Both are offline.pnpm assemble && pnpm test:clean-installbundles the CLI, packs and installs the tarball in a temp directory, and boots that install, through a headless-Chromium check and one real agent run. It needs network access for itsnpm install, the same Chromium download, and no other Clawboo dashboard on ports 18790 to 18809 (stoppnpm devfirst).
pnpm prepublish:check runs the catalog and connector gates, then pnpm assemble and pnpm test:clean-install. Testing lists every CI job, including the cross-platform tests and the website build that have no single local command.5
Add a changeset
Clawboo uses Changesets for versions and changelogs:Choose the
clawboo package and a bump (patch, minor or major), write a short summary, and commit the new file under .changeset/. Every @clawboo/* library is private and only clawboo publishes, but the dashboard (apps/web) ships inside it. So add a changeset for any change a user of the npm package would notice, dashboard changes included. Docs-only, CI-only and test-only changes need none. Release process has the details.6
Open the pull request
Push the branch and open a pull request; the template walks the checklist. Keep one concern per pull request, add a test for what you add (Vitest for logic, the jsdom project for components, Playwright for new end-to-end behavior), and get CI green before you ask for review. Pull requests are squash-merged into
main.Keep the pnpm-lock.yaml diff small. If it grows by thousands of lines, you are on a different pnpm: run corepack enable, then pnpm install, and commit only the intended change. Dependabot opens grouped dependency updates weekly, so you rarely need to touch the lockfile by hand.Your first contribution
Issues labeledgood first issue are scoped small and name the files to touch. Comment on the one you want and a maintainer assigns it to you. Good areas that rarely need core changes: a marketplace team template, a docs page, a provider or runtime icon, or a test for an uncovered component. If you are unsure whether an idea fits, open a Discussion before you write code. A half-finished pull request with a question is welcome.
Documentation changes
Thedocs/ directory is this site: hand-edited Mintlify pages with no build step. Merging to main redeploys docs.claw.boo as it is, so the files in your diff are exactly what ships.
pnpm check:docs catches both, and it also runs inside pnpm lint and CI’s Lint job. For a full check, use the Mintlify CLI: npx mint validate runs a strict build, and npx mint broken-links --check-anchors checks links and anchors. Mintlify keeps / and quote characters in heading anchors, so link to the page rather than to a heading that contains them. docs/README.md covers the layout, the hand-maintained docs.json navigation and local preview.
Contributing a marketplace pack
Agent and team content lives incatalog/, a plain content folder outside the workspace. Edit catalog/packs/<publisher>/<slug>/**, run pnpm catalog:build to regenerate catalog/dist and the compiled seed, run pnpm catalog:verify, and commit the regenerated catalog/dist/** with your change. A pull request that touches only catalog/ runs the short catalog-ci.yml instead of the full matrix, except for catalog/packs/clawboo/** (the seed compiled into the npm package), which gets the full matrix.
Packs are reviewed as writing and merged by hand. CONTRIBUTING.md has the review bar: a description is one or two sentences, IDENTITY.md is the full instruction body, a pack with provenance.repo ships a NOTICE.md, a team has at least two members, and new categories are declared. The format is in the marketplace catalog reference.
Code guidelines
Review and, where possible, lint enforce these:- TypeScript strict. No
any, no@ts-ignore, no leakingunknown. - No
console.log. Log through@clawboo/logger(pino). - Lucide icons only, never emoji in the UI.
- Theme tokens, never raw hex. Use the CSS variables and Tailwind tokens; brand marks are the only exception. See the design system.
- Keep new database columns addable. There is no migration ladder; Schema changes lists the rules a new column must meet.
- Version every persisted client store. A zustand
persiststore sets bothversionandmigrate, and the migrate is a pure exported function with its own test. - Pollers pause when the tab is hidden. A new interval refresh uses
useVisiblePollingfromapps/web/src/lib/useVisiblePolling.ts, not a baresetInterval. - Schema fixtures are append-only. Never edit
packages/pack-format/src/__fixtures__/v1/*.json; a changed shape gets a fixture under the new version’s folder. Each version has aminimal.jsonand akitchen-sink.jsonthat sets every optional field. - Pure where it claims to be. Policy and projection functions stay free of side effects and unit-testable.
- No secrets in logs, responses or storage. Show that a credential is present (the env var name and true or false), never its value. See Security.
Architecture rules
A change must keep the architecture invariants. The ones a first contribution is most likely to meet:- The agent registry says who exists; the OpenClaw Gateway says how OpenClaw agents run. Read agents through an
AgentSource, not straight off the Gateway client. - Packages never import apps. Dependencies flow one way:
apps/webimportspackages/**, and the adapters import@clawboo/executor. Lint enforces it; see Monorepo and build. - Every runtime is a
RuntimeAdapter. A new runtime implements the trait and emits the normalizedRuntimeEventstream instead of adding special cases to the orchestrator. - The board is the record for task and coordination state. Prefer board changes over parsing prose; see Board internals.
- Schema changes are additive. An upgrade only adds missing columns. It never removes a column or changes one’s type or constraints, so those are not in-place upgrades.
Releases
Releases are automated and maintainer-only. When a changeset lands onmain, publish.yml opens a pull request titled chore: version packages. Merging it bumps the version, updates the changelog and publishes the clawboo package to npm; nothing else publishes, and nobody runs npm publish by hand. Before it publishes, the workflow reruns the build, lint, typecheck, tests, the catalog gate and the clean-install gate. It does not rerun every pull request check, and it needs the network. See Release process.
License
By contributing, you agree that your contributions are licensed under the MIT License. See License and notices.Related
CONTRIBUTING.md: the process document this page follows.- Contributor overview: the repo map, the architecture and the caution surfaces.
- Testing: the test layers and every CI job.
- Release process: changesets and the publish workflow.