Contributing
How to contribute to The Mesh open-source project
Contributing
The Mesh is AGPL v3 licensed and community-driven. We welcome contributions of all kinds.
Quick Start
# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/the-mesh
cd the-mesh
git checkout dev
git remote add upstream https://github.com/Metatransformer/the-mesh
# 2. Install and run
cp .env.example .env
pnpm install
make dev-native
# → Go server at localhost:4000, Next.js at localhost:3000
# 3. Make changes on a branch
git checkout -b feature/my-change
# ... code ...
cd packages/server && go test ./... # test
git push origin feature/my-change
# Open PR targeting devPrerequisites
| Tool | Version |
|---|---|
| Go | 1.24+ |
| Node.js | 22+ |
| pnpm | 10+ |
| Docker | Latest (optional, for k3d) |
Branch Model
dev → all development (PRs go here)
main → stable releases (maintainers promote)Always PR against dev. Maintainers merge dev → main for releases, which triggers CI/CD.
What Needs Help
| Area | Difficulty | Examples |
|---|---|---|
| Bug fixes | Easy | Check open issues |
| Documentation | Easy | Fix stale docs, add guides, improve examples |
| Bot examples | Easy-Medium | Write bots in Python, Go, Rust, etc. |
| Test coverage | Medium | Go unit tests, Playwright E2E tests |
| UI/UX | Medium | Responsive fixes, accessibility, new views |
| Federation | Hard | Cross-mesh communication, CRDT sync |
| Security | Hard | UCAN enforcement, output classification |
See the full Roadmap for planned features.
PR Checklist
- Target branch is
dev - Tests pass (
cd packages/server && go test ./...) -
CHANGELOG.mdupdated under## [Unreleased] - Docs updated if user-facing (
apps/docs/content/docs/) - One feature or fix per PR
Architecture
Two services:
- Go server (
packages/server/, port 4000) — core: auth, storage, WebSocket, REST API, RBAC, bots - Next.js frontend (
apps/web/, port 3000) — static client, zero server-side logic
Read the full Architecture page before diving in.
Testing
cd packages/server && go test ./... # Go unit tests
cd packages/server && bash test-e2e.sh # Go E2E (28 tests)
pnpm test:e2e # Playwright browser tests
pnpm test # Affected tests onlyCommunity
- Discord — questions and discussion
- GitHub Issues — bugs and features
- GitHub Discussions — ideas and RFCs
Full Guide
See CONTRIBUTING.md for the complete contributor guide with code style, project layout, and deployment details.