Contributing to Hephaestus

Contributing to Hephaestus

Thank you for your interest in contributing to Hephaestus! We welcome contributions from the community.

🚀 Getting Started

Prerequisites

• Python 3.10+
• Node.js 20+ and npm
• Docker (for Qdrant)
• tmux
• Git
• Claude Code (for testing agent functionality)

Development Setup

1. **Clone and setup the repository**

   git clone https://github.com/Ido-Levi/Hephaestus.git
   cd Hephaestus

2. **Set up Python environment**

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. **Configure environment variables**

   cp .env.example .env
   # Edit .env with your API keys

4. **Start required services**

   # Terminal 1: Qdrant
   docker run -d -p 6333:6333 qdrant/qdrant
   
   # Terminal 2: Frontend
   cd frontend
   npm install
   npm run dev

5. **Initialize databases**

   python scripts/init_db.py
   python scripts/init_qdrant.py

6. **Run the server**

   python run_server.py

📋 How to Contribute

Reporting Bugs

Found a bug? Please open an issue using the **Bug Report** template. Include:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Environment details (OS, Python version, etc.)
• Relevant logs or error messages

Suggesting Features

Have an idea? Open a **Feature Request** issue with:

• Clear use case description
• Why this feature would be valuable
• Proposed implementation approach (if you have one)

Submitting Code

1. **Fork the repository**

2. **Create a feature branch**

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/issue-description

3. **Make your changes**

   • Write clear, documented code
   • Follow existing code style
   • Add tests for new functionality
   • Update documentation as needed

4. **Test your changes**

   # Run tests
   pytest
   
   # Check code style
   black src/ tests/
   flake8 src/ tests/
   
   # Type checking
   mypy src/

5. **Commit your changes**

   git add .
   git commit -m "feat: Add clear description of your changes"

   Follow conventional commit format:

   • feat: New features
   • fix: Bug fixes
   • docs: Documentation changes
   • test: Test additions/changes
   • refactor: Code refactoring
   • chore: Maintenance tasks

6. **Push and create a Pull Request**

   git push origin feature/your-feature-name

   Then create a PR on GitHub with:

   • Clear title and description
   • Link to related issues
   • Screenshots/videos if UI changes
   • Test results

🎨 Code Style Guidelines

Python

• Follow PEP 8
• Use type hints for function parameters and returns
• Write docstrings for classes and functions
• Maximum line length: 100 characters
• Use black for formatting

**Example:**

def create_task(
    descripti