ClawdBot on GitHub

📦 Repository Overview

Official Repository

URL: github.com/steipete/ClawdBot

Creator: Peter Steinberger (Founder of PSPDFKit)

First Release: 2024

Latest Version: Check Releases

What's in the Repository?

• 🔧 Gateway Server: Core routing and message handling
• 📱 Channel Adapters: Integrations for Telegram, WhatsApp, Discord, etc.
• 🤖 AI Providers: Connectors for Claude, GPT-4, Gemini, Ollama
• 🌐 Browser Tools: Puppeteer-based automation
• 🧠 Memory System: Conversation storage and retrieval
• 🔌 Skills Framework: Plugin architecture
• 📚 Documentation: Setup guides, API docs
• 🧪 Tests: Unit and integration tests

🗂️ Code Structure

ClawdBot/
├── src/
│   ├── gateway/          # Core server logic
│   │   ├── server.ts
│   │   ├── router.ts
│   │   └── config.ts
│   ├── channels/         # Messaging platform integrations
│   │   ├── telegram/
│   │   ├── whatsapp/
│   │   ├── discord/
│   │   └── imessage/
│   ├── providers/        # AI model providers
│   │   ├── anthropic.ts
│   │   ├── openai.ts
│   │   ├── gemini.ts
│   │   └── ollama.ts
│   ├── tools/            # Browser, file system, etc.
│   │   ├── browser.ts
│   │   ├── filesystem.ts
│   │   └── shell.ts
│   ├── memory/           # Conversation storage
│   │   ├── store.ts
│   │   └── retrieval.ts
│   └── skills/           # Plugin system
│       └── manager.ts
├── skills/               # Community skills
├── tests/                # Test suites
├── docs/                 # Documentation
├── config/               # Default configs
├── package.json
└── README.md

Key Files to Understand

1. src/gateway/server.ts

The heart of ClawdBot. Handles incoming messages, routes to AI providers, and sends responses.

2. src/channels/telegram/index.ts

Example of a channel adapter. Shows how messaging platforms integrate with the Gateway.

3. src/providers/anthropic.ts

AI provider implementation. Demonstrates how to connect to Claude API.

4. src/tools/browser.ts

Browser automation using Puppeteer. Core of the web scraping capabilities.

5. src/memory/store.ts

Persistent memory system. Stores conversations as Markdown files.

🚀 Getting Started with Development

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/ClawdBot.git
cd ClawdBot

2. Install Dependencies

npm install

3. Set Up Environment

# Copy example config
cp config/example.yaml config/local.yaml

# Add your API keys
nano config/local.yaml

4. Run in Development Mode

# Start with hot reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

5. Build for Production

npm run build

Development Tools

• TypeScript: Type-safe development
• ESLint: Code quality checks
• Prettier: Code formatting
• Jest: Testing framework
• Nodemon: Auto-restart on changes

🤝 How to Contribute

ClawdBot welcomes contributions! Here's how to get involved:

Ways to Contribute

1. Code Contributions

• 🐛 Fix bugs
• ✨ Add new features
• 📱 Create new channel adapters
• 🔌 Build skills/plugins
• ⚡ Performance improvements
• 🧪 Write tests

2. Documentation

• 📝 Improve README
• 📚 Write tutorials
• 🌍 Translate docs
• 🎥 Create video guides

3. Community Support

• 💬 Answer questions on Discord
• 🐛 Triage GitHub issues
• 👥 Help newcomers

Contribution Guidelines

Code Style

# Follow existing patterns
# Use TypeScript for type safety
# Write descriptive commit messages
# Add tests for new features
# Update documentation

Commit Message Format

type(scope): brief description

Examples:
feat(telegram): add inline keyboard support
fix(browser): resolve timeout issues
docs(readme): update installation steps
test(memory): add unit tests for retrieval

Before Submitting

# Run tests
npm test

# Check linting
npm run lint

# Format code
npm run format

# Build successfully
npm run build

🐛 Reporting Issues

Before Creating an Issue

• ✅ Search existing issues to avoid duplicates
• ✅ Check if it's already fixed in the latest version
• ✅ Read the troubleshooting guide
• ✅ Try to reproduce the issue

Issue Template

**Bug Description**
Clear description of what went wrong

**Steps to Reproduce**
1. Start ClawdBot with...
2. Send message...
3. Error occurs...

**Expected Behavior**
What should have happened

**Actual Behavior**
What actually happened

**Environment**
- OS: macOS 14.2
- Node.js: v22.0.0
- ClawdBot: v1.5.0
- AI Model: Claude 3.5 Sonnet

**Logs**
```
[Paste relevant logs here]
```

**Additional Context**
Any other relevant information

Issue Labels

🔀 Submitting Pull Requests

PR Workflow

1. Create a Branch

git checkout -b feature/my-new-feature
# or
git checkout -b fix/bug-description

2. Make Changes

# Write code
# Add tests
# Update docs
# Commit changes
git add .
git commit -m "feat(scope): add awesome feature"

3. Push to Your Fork

git push origin feature/my-new-feature

4. Open Pull Request

Go to GitHub and click "New Pull Request"

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests pass locally
- [ ] Added new tests
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-reviewed code
- [ ] Commented complex code
- [ ] Updated documentation
- [ ] No new warnings

## Related Issues
Fixes #123
Related to #456

Review Process

• 🔍 Maintainers review your code
• 💬 Address feedback and make changes
• ✅ Once approved, PR is merged
• 🎉 Your contribution is live!

Tips for Faster Approval

• ✅ Keep PRs focused and small
• ✅ Write clear descriptions
• ✅ Include tests
• ✅ Follow code style
• ✅ Be responsive to feedback

👥 Community & Resources

Official Channels

GitHub Discussions

github.com/steipete/ClawdBot/discussions

• 💡 Feature ideas
• ❓ Q&A
• 📢 Announcements
• 💬 General chat

Discord Server

Join the community Discord (link in GitHub README)

• #general - General discussion
• #support - Get help
• #development - Dev talk
• #showcase - Show your projects

Reddit

r/ClawdBot - Community discussions and tips

Learning Resources

Official Documentation

• docs.clawd.bot - Complete docs
• GitHub Wiki - Community guides

Code Examples

• examples/ - Sample implementations
• GitHub Topics - Community projects

Video Tutorials

• YouTube: Search "ClawdBot tutorial"
• Creator's blog: steipete.me

Notable Contributors

See Contributors page for the full list of amazing people building ClawdBot!

❓ Developer FAQ