Contributing Guide

​

Code of Conduct

​

Getting Started

​

Prerequisites

• Python ≥3.11
• Git
• A text editor or IDE

​

Development Setup

1. Fork and clone the repository

git clone https://github.com/YOUR_USERNAME/nanobot.git
cd nanobot

2. Install in development mode

pip install -e .

3. Set up your config

nanobot onboard

4. Verify installation

nanobot status

​

Development Workflow

​

Making Changes

1. Create a feature branch

git checkout -b feature/your-feature-name

2. Make your changes

3. Test your changes

# Test in CLI mode
nanobot agent -m "Test message"

# Test with gateway
nanobot gateway

4. Verify code quality

• Follows the existing style (simple, readable, minimal)
• Includes docstrings for public functions and classes
• Handles errors gracefully with logging
• Keeps the line count low (remember: ~4,000 lines of core agent code)

​

Submitting Changes

1. Commit your changes

git add .
git commit -m "Add feature: brief description"

• Start with a verb (Add, Fix, Update, Remove)
• Keep the first line under 50 characters
• Add details in the body if needed

2. Push to your fork

git push origin feature/your-feature-name

3. Open a Pull Request

• Go to the main nanobot repository
• Click “New Pull Request”
• Select your branch
• Fill in the PR template with:
  • What changes you made
  • Why you made them
  • How to test them

​

What to Contribute

​

Priority Areas

• Multi-modal support (images, voice, video)
• Long-term memory improvements
• Better reasoning capabilities
• New channel integrations
• New provider integrations

​

Good First Issues

• Well-defined
• Limited in scope
• Good for learning the codebase

​

Bug Fixes

1. Check if it’s already reported in GitHub Issues
2. If not, open a new issue with:
   • Steps to reproduce
   • Expected behavior
   • Actual behavior
   • Your environment (OS, Python version)
3. Wait for confirmation, then submit a fix

​

Code Style Guidelines

​

Python Style

• Follow PEP 8 loosely (readability over strict compliance)
• Use type hints for function signatures
• Keep functions small and focused
• Prefer explicit over implicit
• Use loguru for logging

​

Example

from loguru import logger

def process_message(content: str, sender_id: str) -> dict:
    """Process an incoming message.
    
    Args:
        content: The message text.
        sender_id: The sender's identifier.
    
    Returns:
        A dict with processing results.
    """
    logger.debug("Processing message from {}", sender_id)
    
    # Your code here
    result = {"status": "ok"}
    
    return result

​

Code Organization

• One class or feature per file when possible
• Use __init__.py to expose public APIs
• Keep imports at the top, grouped:
  1. Standard library
  2. Third-party
  3. Local imports

​

Testing

​

Manual Testing

1. Test CLI mode

nanobot agent -m "Hello"

2. Test gateway mode (if you modified channels)

nanobot gateway

3. Test edge cases

• Empty input
• Very long messages
• Special characters
• Error conditions

​

Integration Testing

• Test with multiple providers (OpenRouter, Anthropic, etc.)
• Test with different channels (Telegram, Discord, etc.)
• Test with MCP servers enabled
• Test with restrictToWorkspace enabled

​

Documentation

1. Update docstrings in the code
2. Update README.md if it affects user-facing features
3. Add examples in comments or docs

​

Getting Help

• Discord: Join the Discord community
• Discussions: Start a GitHub Discussion
• Issues: Search existing GitHub Issues

​

Review Process

1. A maintainer will review your PR
2. They may request changes or ask questions
3. Make requested changes by pushing to your branch
4. Once approved, a maintainer will merge your PR

​

License

​

Recognition

• The README contributors section
• The GitHub contributors graph
• Release notes (for significant contributions)