Contributing Guide

Learn how to contribute to Tiny Claw - from setup to submitting pull requests

Contributing to Tiny Claw

Thanks for your interest in contributing to Tiny Claw! Every contribution - code, docs, bug reports, or ideas - helps make AI companions more accessible to everyone.

Please read our Code of Conduct before getting started.

Contributor License Agreement (CLA)

By submitting a pull request, you agree to our Contributor License Agreement. The CLA is required because Tiny Claw uses a dual-licensing model (GPL-3.0 + Commercial). First-time contributors will be prompted to sign the CLA automatically via CLA Assistant when opening a PR.

Getting Started

Prerequisites

Bun

Latest stable version

Git

Version control

GitHub Account

For contributions

Fork & Clone

# Fork the repo on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/tinyclaw.git
cd tinyclaw
git remote add upstream https://github.com/warengonzaga/tinyclaw.git
bun install

Run in Development

bun dev        # Start the CLI in development mode
bun dev:ui     # Start the web UI in development mode
bun build      # Build all packages
bun test       # Run the full test suite

Project Structure

Tiny Claw is a Bun workspace monorepo. The core stays tiny - everything else is a plugin.

tinyclaw/
  packages/        Core library packages (tiny, focused, no circular deps)
  plugins/         Plugin packages (channels, providers, tools)
  src/cli/         CLI entry point
  src/web/         Web UI (Svelte 5)

See the Architecture documentation for the full architecture overview.

Development Workflow

1. Create an issue first

   Describe what you want to work on before writing code. This helps avoid duplicate work and ensures alignment with project goals.

2. Sync with upstream

   Keep your fork current:

   git fetch upstream && git merge upstream/dev
   
3. Create a branch

   Create a branch from dev using one of these prefixes:

   • feature/* - new functionality
   • fix/* - bug fixes
   • docs/* - documentation changes
   • refactor/* - code restructuring without behavior changes
4. Make your changes

   Write code, add tests, update docs as needed.

5. Verify locally

   bun build     # Ensure it compiles
   bun test      # Ensure tests pass
   
6. Submit a PR

   Target the dev branch (never main).

Commit Convention

This project follows the Clean Commit convention.

Emoji	Type	What it covers
📦	new	Adding new features, files, or capabilities
🔧	update	Changing existing code, refactoring, improvements
🗑️	remove	Removing code, files, features, or dependencies
🔒	security	Security fixes, patches, vulnerability resolutions
⚙️	setup	Project configs, CI/CD, tooling, build systems
☕	chore	Maintenance tasks, dependency updates, housekeeping
🧪	test	Adding, updating, or fixing tests
📖	docs	Documentation changes and updates
🚀	release	Version releases and release preparation

Examples

📦 new (core): add conversation memory system
🔧 update (api): improve error handling
🧪 test (memory): add unit tests for temporal decay
📖 docs: update installation instructions

Rules: lowercase type, present tense, no trailing period, under 72 characters.

Pull Request Guidelines

Before Submitting

Checklist

• An issue exists and is referenced in the PR description (e.g., Closes #42)
• PR targets the dev branch
• All commits follow the Clean Commit convention
• Code builds successfully (bun build)
• Tests pass (bun test)
• Documentation is updated (if applicable)
• CLA is signed

PR Description

Include a clear summary of what changed and why. Reference the issue number. If the change is visual, include screenshots or recordings.

Review Process

• A maintainer will review your PR and may request changes.
• Please respond to feedback promptly - stale PRs may be closed after 30 days of inactivity.
• Once approved, a maintainer will merge your PR.

Writing Tests

Tests live in tests/ directories alongside each package’s src/. We use Bun’s built-in test runner.

bun test                          # Run all tests
bun test packages/memory          # Run tests for a specific package
bun test --watch                  # Run in watch mode

When contributing code, please:

• Add tests for new features and bug fixes.
• Keep tests focused - one behavior per test.
• Use descriptive test names that explain what is being tested.

Code Style

TypeScript

Use strong typing - avoid any

Consistency

Follow existing patterns and conventions

Simplicity

Keep functions small and focused

Error Handling

Handle errors gracefully - don’t swallow exceptions

No circular dependencies between packages.

Reporting Bugs

Open a new issue and include:

• A clear, descriptive title.
• Steps to reproduce the issue.
• Expected vs. actual behavior.
• Your environment (OS, Bun version, Node version if applicable).
• Relevant logs or error messages.

Please search existing issues first to avoid duplicates.

Suggesting Features

Feature ideas are welcome! Open an issue with:

• A clear description of the problem the feature solves.
• Your proposed solution or approach.
• Any alternatives you’ve considered.

Getting Help

Documentation

Check the docs for architecture and design info

Issues & Discussions

Browse existing conversations

Follow on X

Get updates from @TinyClawAI and @warengonzaga

---

Made with love by the Tiny Claw community