Contributing

Human uses a vtable-driven architecture. New features are added by implementing vtables and registering them in factory code.

Vtable interface pattern

1. Define a vtable struct (function pointers)
2. Implement the vtable with concrete functions
3. Create a “context” struct holding state
4. Register in the appropriate factory

Callers receive a struct { void *ctx; const vtable_t *vtable }. The caller does not own the vtable; it is typically static. The caller must own the context (or a wrapper that owns it) — never return a pointer to a temporary.

Adding a provider

1. Create src/providers/<name>.c
2. Implement hu_provider_t vtable: chat, supports_native_tools, get_name, deinit
3. Add hu_<name>_create factory function
4. Register in src/providers/factory.c (name check + create call)
5. Add tests for vtable wiring and error paths
6. Document in providers/ docs

Adding a channel

1. Create src/channels/<name>.c
2. Implement hu_channel_t vtable: start, stop, send, name, health_check
3. Add create function with config (token, allowlist, etc.)
4. Add CMake option HU_ENABLE_<CHANNEL>
5. Wire in channel manager / daemon
6. Add webhook path in gateway if needed
7. Document in channels/ docs

Adding a tool

1. Create src/tools/<name>.c
2. Implement hu_tool_t vtable: execute, name, description, parameters_json, deinit
3. Validate and sanitize all inputs; return hu_tool_result_t
4. Add HU_IS_TEST guard if the tool spawns processes or opens URLs
5. Register in src/tools/factory.c
6. Document in tools/overview.mdx

Adding a memory backend

1. Create src/memory/<name>.c
2. Implement hu_memory_t vtable
3. Add CMake option and factory registration
4. Document in memory/overview.mdx

Adding a peripheral

1. Create src/peripherals/<name>.c
2. Implement hu_peripheral_t vtable: name, board_type, health_check, read, write, flash, capabilities, destroy
3. Register in peripheral factory
4. Document in peripherals/overview.mdx

Testing requirements

• 3,185+ tests must pass
• Zero ASan errors — AddressSanitizer enabled in dev builds
• Use HU_IS_TEST to skip side effects (network, spawning, real hardware)
• Tests must be deterministic; no flaky behavior
• Run: cmake --build build && ./build/human_tests

Code style

• Identifiers: snake_case (functions, variables, fields)
• Types: hu_<name>_t (e.g. hu_provider_t, hu_channel_t)
• Constants/macros: HU_SCREAMING_SNAKE_CASE
• Public functions: hu_<module>_<action>
• Factory keys: lowercase, stable (e.g. "openai", "telegram")

Validation before commit

cd build
cmake --build . -j$(nproc)
./human_tests

For release builds:

cmake .. -DCMAKE_BUILD_TYPE=MinSizeRel -DHU_ENABLE_LTO=ON
cmake --build .

Git hooks

Activate pre-configured hooks:

git config core.hooksPath .githooks

• pre-commit: Format checks
• pre-push: Build and run tests

Bypass in emergency: git commit --no-verify / git push --no-verify.