null·menu
Menu
Browse documentation

Develop

Contributing

verified · v2026.5.29 edit on github
On this page 5 sections

All development happens in the open at github.com/nullclaw. The repos share one toolchain, one CI system and one release convention, so contributing to a second component feels like the first.

Toolchain

One version, everywhere:

Requirement Value
Zig 0.16.0 exactly — every repo pins it
Node/npm Only for NullHub's embedded Svelte UI
Anything else No — SQLite and C deps are vendored

The standard loop is the same in every repo:

git clone https://github.com/nullclaw/<repo>.git
cd <repo>
zig build
zig build test

NullClaw uses zig build test --summary all; NullTickets adds bash tests/test_e2e.sh; NullPantry has suite targets (zig build test-api, test-agent-memory, test-vector) plus opt-in contract tests against external backends (zig build qdrant-contract and friends).

Test culture

Tests are the family's main quality gate, and the numbers are taken seriously: NullClaw carries 7,400+ in-tree tests, NullBoiler 355 unit tests plus an e2e suite with mock workers, nllclw ~330 test blocks (more with the shell tool compiled in), and NullHub runs backend integration tests against a real hub process in a temporary home directory. A PR without tests for its change will be asked for them.

Shared CI: NullBuilder

CI, nightlies and releases are reusable GitHub Actions workflows in nullclaw/nullbuilder. Because v1 is a mutable branch, consuming repos pin its reviewed snapshot and update it only after reviewing upstream changes:

jobs:
  ci:
    # NullBuilder v1 snapshot; review upstream before updating this full SHA.
    uses: nullclaw/nullbuilder/.github/workflows/zig-ci.yml@2b9c2f2e7bb0ac085baea1c33b4f08beaf5c7fac
    permissions:
      contents: read
    with:
      binary_name: nullclaw
      artifact_prefix: nullclaw

The CI workflow runs tests, cross-compiles ReleaseSmall binaries for a configurable target matrix, and reports test count, MaxRSS and binary size in the job summary — binary size is a tracked metric here, not an afterthought. zig-nightly.yml and zig-release.yml cover nightly builds (12-target default matrix, including Android via the NDK) and tag-driven releases with optional multi-arch Docker publish to ghcr.io. General-purpose third-party actions are pinned to commit SHAs, and the bundled Zig installer verifies its archive; NullBuilder's three internal composite helpers remain referenced through its mutable v1 branch.

Releases

Versions are CalVer: pushing a v2026.x.y tag triggers the release workflow, which injects the version, builds the matrix, and publishes binaries with generated notes. Most repos carry a RELEASING.md with their specifics — NullClaw, NullHub, NullBoiler, NullTickets and NullWatch all do.

Where to contribute

  • Code and issues. NullClaw ships a CONTRIBUTING.md; NullHub has TESTING.md describing its testing strategy and roadmap, plus multiple external contributors already. AGENTS.md / CLAUDE.md files in most repos carry conventions for coding agents — read them, whichever kind of contributor you are.
  • Docs. NullClaw maintains English and Chinese docs; nllclw is localized into 11 languages. Translation fixes are welcome, low-risk first PRs.
  • Integrations. Bridges, SDKs and adapters (like the community nullwatch-python-sdk) can live outside the org entirely — see Integrations.