hermes-agent/CONTRIBUTING.md

Contributing to Hermes Agent

Thank you for your interest in contributing to Hermes Agent! This document provides guidelines and information for contributors.

Getting Started

Prerequisites

• Python 3.11+
• An OpenRouter API key (for running the agent)
• Git

Development Setup

1. Clone the repository:

   git clone https://github.com/NousResearch/hermes-agent.git
   cd hermes-agent
   

2. Install dependencies:

   pip install -e .
   # Or using uv
   uv pip install -e .
   

3. Copy the example environment file and configure:

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

4. Run the setup script (optional, for shell autocompletion):

   ./setup-hermes.sh
   

Project Structure

hermes-agent/
├── run_agent.py          # Main AIAgent class
├── cli.py                # Interactive CLI
├── model_tools.py        # Tool registry orchestration
├── toolsets.py           # Toolset definitions
├── agent/                # Agent internals (extracted modules)
│   ├── prompt_builder.py   # System prompt assembly
│   ├── context_compressor.py
│   ├── auxiliary_client.py
│   └── ...
├── tools/                # Individual tool implementations
│   ├── registry.py         # Central tool registry
│   ├── terminal_tool.py
│   ├── web_tools.py
│   ├── file_tools.py
│   └── ...
├── gateway/              # Multi-platform messaging gateway
│   ├── run.py
│   ├── platforms/          # Platform adapters (Telegram, Discord, etc.)
│   └── ...
├── skills/               # Built-in skills
├── docs/                 # Documentation
└── tests/                # Test suite

Contributing Guidelines

Code Style

• Follow PEP 8 for Python code
• Use type hints where practical
• Add docstrings to functions and classes (Google-style docstrings preferred)
• Keep lines under 100 characters when reasonable

Adding a New Tool

Tools self-register with the central registry. To add a new tool:

1. Create a new file in tools/ (e.g., tools/my_tool.py)

2. Define your tool handler and schema:

   #!/usr/bin/env python3
   """
   My Tool Module - Brief description
   
   Longer description of what the tool does.
   """
   
   import json
   from tools.registry import registry
   
   
   def my_tool_handler(args: dict, **kwargs) -> str:
       """Execute the tool and return JSON result."""
       # Your implementation here
       return json.dumps({"result": "success"})
   
   
   def check_my_tool_requirements() -> bool:
       """Check if tool dependencies are available."""
       return True  # Or actual availability check
   
   
   MY_TOOL_SCHEMA = {
       "name": "my_tool",
       "description": "What this tool does...",
       "parameters": {
           "type": "object",
           "properties": {
               "param1": {
                   "type": "string",
                   "description": "Description of param1"
               }
           },
           "required": ["param1"]
       }
   }
   
   # Register with the central registry
   registry.register(
       name="my_tool",
       toolset="my_toolset",
       schema=MY_TOOL_SCHEMA,
       handler=lambda args, **kw: my_tool_handler(args, **kw),
       check_fn=check_my_tool_requirements,
   )
   

3. Add the import to model_tools.py in _discover_tools():

   _modules = [
       # ... existing modules ...
       "tools.my_tool",
   ]
   

4. Add your toolset to toolsets.py if it's a new category

Adding a Skill

Skills are markdown documents with YAML frontmatter. Create a new skill:

1. Create a directory in skills/:

   skills/my-skill/
   └── SKILL.md
   

2. Write the skill file with proper frontmatter:

   ---
   name: my-skill
   description: Brief description of what this skill does
   version: 1.0.0
   author: Your Name
   tags: [category, subcategory]
   ---
   
   # My Skill
   
   Instructions for the agent when using this skill...
   

Pull Request Process

1. Fork the repository and create a feature branch:

   git checkout -b feat/my-feature
   # or
   git checkout -b fix/issue-description
   

2. Make your changes with clear, focused commits

3. Test your changes:

   # Run the test suite
   pytest tests/
   
   # Test manually with the CLI
   python cli.py
   

4. Update documentation if needed

5. Submit a pull request with:

   • Clear title following conventional commits (e.g., feat(tools):, fix(cli):, docs:)
   • Description of what changed and why
   • Reference to any related issues

Commit Message Format

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• refactor: Code change that neither fixes a bug nor adds a feature
• test: Adding or correcting tests
• chore: Changes to build process or auxiliary tools

Scopes: cli, gateway, tools, skills, agent, etc.

Security Considerations

When contributing tools that interact with external resources:

• Skills Guard: External skills pass through security scanning (tools/skills_guard.py)
• Dangerous Commands: Terminal commands are checked against patterns (tools/approval.py)
• Memory Scanning: Memory entries are scanned for injection attempts
• Context Scanning: AGENTS.md and similar files are scanned before prompt injection

If your change affects security, please note this in your PR.

Reporting Issues

• Use GitHub Issues for bug reports and feature requests
• Include steps to reproduce for bugs
• Include system information (OS, Python version)
• Check existing issues before creating duplicates

Questions?

• Open a GitHub Discussion for general questions
• Join the Nous Research community for real-time chat

License

By contributing, you agree that your contributions will be licensed under the same license as the project.