Contributing to Clawith 🦞

Thanks for your interest in contributing! Whether it's a bug fix, new feature, translation, or documentation improvement — every contribution matters.

Quick Start

1. Fork this repo and clone your fork
2. Set up the dev environment:

   bash setup.sh    # Backend + frontend + database
   bash restart.sh  # Start services → http://localhost:3008
   

3. Create a branch: git checkout -b my-feature
4. Make your changes
5. Push and open a Pull Request

What Can I Contribute?

Area	Examples
🐛 Bug fixes	UI glitches, API errors, edge cases
✨ Features	New agent skills, tools, UI improvements
🔧 MCP Integrations	New MCP server connectors
🌍 Translations	New languages or improving existing ones
📖 Documentation	README, guides, code comments
🧪 Tests	Unit tests, integration tests

New to the project? Look for issues labeled good first issue.

Bug Reports

When reporting a bug, please include:

• Steps to reproduce
• Expected vs actual behavior
• Clawith version and deployment method (Docker / Source)
• Logs or screenshots if available

Priority guide:

Type	Priority
Core functions broken (login, agents, security)	🔴 Critical
Non-critical bugs, performance issues	🟡 Medium
Typos, minor UI issues	🟢 Low

Feature Requests

Please describe:

• The problem you're trying to solve
• Your proposed solution (if any)
• Why this would be useful

Pull Request Process

1. Link an issue — Create one first if it doesn't exist
2. Keep it focused — One PR per feature/fix
3. Test your changes — Make sure nothing is broken
4. Follow code style:
   • Backend: Python — formatted with ruff
   • Frontend: TypeScript — standard React conventions
5. Use Fixes #<issue_number> in the PR description

Working on Multiple Features

It is common to develop several improvements in one sitting before submitting. Rather than sending one giant PR, please split your work into smaller, focused PRs — this makes review faster and merges cleaner.

Preferred: one branch per feature from the start

# Start each new feature from a fresh branch off main
git checkout main && git pull
git checkout -b feat/i18n-emoji-cleanup

# ... develop, commit ...

git checkout main
git checkout -b feat/admin-email-templates

# ... develop, commit ...

Each branch becomes one PR. Small, clean, easy to review.

Already mixed everything into one branch? Split it with git add -p

git add -p (patch mode) lets you selectively stage individual change hunks from a file — perfect for creating several commits from one messy branch.

Step-by-step example:

# Assume your branch is called my-big-branch and has 3 logical changes mixed in.
# Goal: create 3 separate PRs from it.

# --- PR 1: emoji cleanup ---
git checkout -b feat/i18n-emoji-cleanup main

# Interactively stage only the emoji-related hunks from en.json and zh.json:
git add -p frontend/src/i18n/en.json   # answer y/n for each hunk
git add -p frontend/src/i18n/zh.json
git commit -m "fix: remove emoji from i18n strings"
git push -u origin feat/i18n-emoji-cleanup
# → open PR

# --- PR 2: hardcoded strings → t() ---
git checkout -b feat/i18n-component-strings main

git add -p frontend/src/pages/AgentDetail.tsx   # stage only t() hunk
git add -p frontend/src/components/ChannelConfig.tsx
git commit -m "feat: replace hardcoded UI strings with i18n t() calls"
git push -u origin feat/i18n-component-strings
# → open PR

# --- PR 3: admin improvements ---
git checkout -b feat/admin-improvements main
git checkout my-big-branch -- frontend/src/pages/AdminCompanies.tsx  # cherry-pick whole file if clean
git commit -m "feat: improve admin company settings"
git push -u origin feat/admin-improvements
# → open PR

Key commands:

Command	What it does
git add -p <file>	Stage hunks interactively (y = yes, n = no, s = split hunk smaller)
git checkout <branch> -- <file>	Copy a whole file from another branch
git cherry-pick <commit>	Apply a single commit to the current branch
git diff main...HEAD -- <file>	Preview what changed in a specific file vs main

Tips

• Commit early, commit often on your dev branch — individual commits are much easier to cherry-pick later than one large commit.
• Use descriptive commit messages (e.g. fix: remove emoji from zh.json, not update stuff).
• If two features touch the same file heavily, submit PR 1 first, wait for it to merge, then rebase PR 2 on main before opening it.

Project Structure

backend/
├── app/
│   ├── api/          # FastAPI route handlers
│   ├── models/       # SQLAlchemy models
│   ├── services/     # Business logic
│   └── core/         # Auth, events, middleware
frontend/
├── src/
│   ├── pages/        # Page components
│   ├── components/   # Reusable UI components
│   ├── stores/       # Zustand state management
│   └── i18n/         # Translations

Language Policy

To ensure all contributors can participate effectively, please use English for issues, PRs, and code comments.

为了确保所有贡献者都能有效参与，请使用英语提交 Issue、PR 和代码注释。

すべてのコントリビューターが効果的に参加できるよう、Issue、PR、コードコメントは英語でお願いします。

모든 기여자가 효과적으로 참여할 수 있도록, Issue, PR, 코드 코멘트는 영어로 작성해 주세요.

Para garantizar que todos los contribuidores puedan participar de manera efectiva, utilice inglés para issues, PRs y comentarios de código.

لضمان مشاركة جميع المساهمين بفعالية، يرجى استخدام اللغة الإنجليزية في الـ Issues وطلبات السحب وتعليقات الكود.

Windows Development

Clawith is primarily developed on Linux/macOS, but can run on Windows with a few adjustments.

Prerequisites

• Python 3.11+ — Install from python.org (check "Add to PATH")
• Node.js 18+ — Install from nodejs.org
• Docker Desktop — For PostgreSQL and Redis (recommended over native installs)

Database & Redis via Docker

docker run -d --name clawith-postgres -p 5432:5432 -e POSTGRES_PASSWORD=yourpass -e POSTGRES_DB=clawith postgres:15
docker run -d --name clawith-redis -p 6379:6379 redis:7

Backend Setup

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# Create .env (copy from .env.example and adjust DATABASE_URL / REDIS_URL)
# Run database migrations
alembic upgrade head

# Start the server
uvicorn app.main:app --host 0.0.0.0 --port 8000

Frontend Setup

cd frontend
npm install
npm run dev

Common Windows Issues

Issue	Solution
UnicodeEncodeError / GBK encoding	Set PYTHONUTF8=1 in environment variables, or run chcp 65001 before starting
System proxy intercepting LLM API calls	Set NO_PROXY=* or unset HTTP_PROXY / HTTPS_PROXY in your terminal
uvicorn --reload crashes with watchfiles	Remove --reload flag, or install watchfiles: pip install watchfiles
File path errors with backslashes	Use pathlib.Path — the codebase already does this in most places

Note: The recommended deployment method is Docker (docker compose up -d), which works identically on Windows, macOS, and Linux. The instructions above are for local development without Docker.

Getting Help

Stuck? Open a Discussion or ask in the related issue. We're happy to help! 🙌