Skip to main content

Extending and Contributing to ZeroClaw

1. Start with the smallest extension surface​

The upstream architecture docs and contribution guide strongly suggest that you should not begin by patching the runtime loop directly. Start with the narrowest surface that already exists.

In practice, most work falls into one of these buckets:

GoalFirst place to look
Add a new model family or wire protocolcrates/zeroclaw-providers/
Add a new chat or ingress platformcrates/zeroclaw-channels/
Add a new agent actioncrates/zeroclaw-tools/
Improve operator config behaviorcrates/zeroclaw-config/
Improve terminal UXzerocode/
Update prose docsdocs/book/src/ in the upstream repo

That pattern exists for a reason: the project wants capability-specific logic at the edge, not special cases buried in the runtime.

2. Learn the trait contract before the implementation​

The key public contracts live in zeroclaw-api. Even if you are only changing a concrete integration, it helps to understand whether you are dealing with:

  • a provider trait contract,
  • a channel trait contract,
  • a tool trait contract.

If you skip that step, it is easy to write code that works locally but fights the architecture.

3. First-party extension guidance​

The official first-party extension docs make a useful distinction:

  • built-in capabilities belong in core crates when they are part of ZeroClaw's baseline contract or need tight safety/runtime integration,
  • external integrations may be better as plugins, skills, MCP servers, or CLI-backed workflows.

That is an important mindset for contributors. Not every new capability should become a permanent built-in.

4. What contributors are expected to read​

The upstream contribution guide specifically tells contributors to read:

  • the repo's root AGENTS.md,
  • the architecture/contribution map,
  • the RFC process for larger changes.

That is a strong signal that ZeroClaw treats contribution discipline as part of the architecture, not as project trivia.

5. Testing and code quality expectations​

The contribution guide calls out these expectations:

  • cargo fmt clean
  • cargo clippy -D warnings clean
  • no unwrap() or expect() in production paths unless the invariant is justified
  • minimal dependencies
  • trait-first design
  • security-by-default
  • inline unit tests and broader integration coverage where appropriate

The documented workspace test command is:

cargo nextest run --locked --workspace --exclude zeroclaw-desktop

For docs and generated references, the upstream guide also notes that some reference pages are generated and should not be edited by hand.

6. Docs and generated reference discipline​

If you contribute to the upstream docs, the guide draws a line between:

  • prose docs in docs/book/src/**/*.md
  • generated reference pages for CLI and config

That matters because "fix the docs" can mean two very different workflows:

  • editing a hand-written concept page,
  • regenerating reference output from the codebase.

For the second case, the guide points to:

cargo mdbook refs

7. PR workflow and review expectations​

The upstream contribution guide documents a conventional flow:

fork -> branch -> commit -> push -> open PR -> review -> merge

A few review expectations stand out:

  • PRs target master
  • the PR template matters
  • validation evidence is required
  • larger changes may need an RFC first
  • reviewers use an explicit taxonomy for blocking issues, warnings, suggestions, and resolved findings

That is helpful context if you are used to more casual OSS repos. ZeroClaw presents itself as a project with a real operating discipline.

8. Best first contributions​

If you want a productive way into the codebase, the official docs suggest areas like:

  • new channel work
  • new provider work
  • docs
  • translations
  • hardware support

In practice, the easiest ramps are usually:

  1. docs,
  2. a focused provider or channel improvement,
  3. a narrowly scoped tool or config enhancement.

Jumping straight into runtime-wide refactors is usually the slowest path to a successful first PR.

9. A practical contributor workflow​

For a first serious upstream change, a good sequence is:

  1. read the architecture overview,
  2. read the contribution guide and RFC expectations,
  3. find the smallest owning crate,
  4. copy the pattern of a nearby existing implementation,
  5. keep the PR narrow,
  6. include real validation evidence.

That aligns with how the project is documented and reviewed today.