Contributing to IronClaw

Guidelines for contributing to the IronClaw project

Welcome Contributors

Thank you for your interest in contributing to IronClaw! This guide will help you get started with contributing code, documentation, and improvements to the project.

Getting Started

Before you begin, make sure you have:

• Rust 1.85+ installed via rustup
• Git for version control
• A GitHub account

See Building from Source for detailed setup instructions.

Development Workflow

1. Fork and Clone

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

# Add upstream remote
git remote add upstream https://github.com/nearai/ironclaw.git

2. Create a Branch

Create a descriptive branch name for your changes:

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

3. Make Your Changes

Write your code following the project’s coding standards:

# Format code
cargo fmt

# Run linter
cargo clippy --all --benches --tests --examples --all-features

# Run tests
cargo test

4. Commit Your Changes

Write clear, concise commit messages:

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

5. Push and Create PR

git push origin feature/your-feature-name

Then create a Pull Request on GitHub with:

• A clear title describing the change
• A detailed description of what changed and why
• Any relevant issue numbers (e.g., “Fixes #123”)

Feature Parity Requirement

IronClaw tracks feature parity with OpenClaw in FEATURE_PARITY.md. This is critical for coordinating development across contributors.

When to Update FEATURE_PARITY.md

Update FEATURE_PARITY.md in the same branch when your change:

• Implements a new feature tracked in the parity matrix
• Completes a partial implementation (🚧 → ✅)
• Starts work on a planned feature (❌ → 🚧)
• Changes the status or behavior of any tracked capability

Required Before Opening a PR

1. Review the relevant rows in FEATURE_PARITY.md
2. Update status markers:
   • ✅ Implemented
   • 🚧 Partial (in progress or incomplete)
   • ❌ Not implemented
   • 🔮 Planned
   • 🚫 Out of scope
   • ➖ N/A (not applicable to Rust)
3. Add notes explaining any deviations or design decisions
4. Include the FEATURE_PARITY.md diff in your commit

Example

If you implement hot-reload for configuration:

| Feature | OpenClaw | IronClaw | Notes |
|---------|----------|----------|-------|
- | Hot-reload | ✅ | ❌ | |
+ | Hot-reload | ✅ | ✅ | Uses notify crate for file watching |

Code Quality Standards

Formatting

All code must be formatted with rustfmt:

cargo fmt

Linting

Code should pass clippy without warnings:

cargo clippy --all --benches --tests --examples --all-features

Testing

Add tests for new functionality:

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run tests with logging
RUST_LOG=ironclaw=debug cargo test

See Running Tests for more details.

Project Structure

ironclaw/
├── src/              # Main source code
│   ├── agent/       # Agent loop and message handling
│   ├── channels/    # Channel implementations
│   ├── llm/         # LLM provider integrations
│   ├── memory/      # Workspace and vector memory
│   ├── safety/      # Security and sanitization
│   ├── sandbox/     # WASM and Docker sandboxes
│   └── tools/       # Built-in tools
├── channels-src/    # WASM channel source code
│   ├── telegram/   # Telegram WASM channel
│   ├── slack/      # Slack WASM channel
│   └── discord/    # Discord WASM channel
├── tools-src/       # WASM tool source code
│   ├── github/     # GitHub integration
│   ├── gmail/      # Gmail tool
│   └── slack/      # Slack tool
├── migrations/      # Database migrations
└── tests/           # Integration tests

Coding Conventions

Rust Style

• Follow the Rust API Guidelines
• Use snake_case for functions and variables
• Use PascalCase for types and traits
• Use SCREAMING_SNAKE_CASE for constants
• Add documentation comments (///) for public APIs

Error Handling

• Use Result<T, E> for fallible operations
• Use anyhow::Result for application errors
• Use custom error types with thiserror for library code
• Provide context with .context() from anyhow

Async Code

• Use async/await for I/O operations
• Use tokio::spawn for concurrent tasks
• Avoid blocking operations in async contexts

Documentation

Code Documentation

Document all public APIs:

/// Executes a tool with the given parameters.
///
/// # Arguments
///
/// * `tool_name` - The name of the tool to execute
/// * `params` - JSON parameters for the tool
///
/// # Returns
///
/// Returns the tool execution result or an error.
///
/// # Errors
///
/// Returns an error if the tool is not found or execution fails.
pub async fn execute_tool(
    tool_name: &str,
    params: serde_json::Value,
) -> anyhow::Result<ToolResult> {
    // implementation
}

User Documentation

For user-facing features, consider adding documentation in docs/.

Security Considerations

IronClaw is a security-focused project. Keep these principles in mind:

Defense in Depth

• Always validate and sanitize external input
• Use sandboxing (WASM/Docker) for untrusted code
• Implement capability-based permissions
• Detect and prevent prompt injection

Secrets Management

• Never log secrets or credentials
• Use the secrets encryption system
• Inject credentials at the host boundary
• Scan for secret exfiltration attempts

SSRF Protection

• Validate all URLs and endpoints
• Use allowlists for external requests
• Block private IP ranges and localhost
• Validate redirect targets

Testing Requirements

Unit Tests

Add unit tests for new functionality:

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_feature() {
        // Test implementation
    }
}

Integration Tests

For features that interact with external systems, add integration tests in tests/.

Database Tests

IronClaw uses libSQL for tests by default (no external database required):

cargo test

For PostgreSQL integration tests:

# Create test database
createdb ironclaw_test

# Run integration tests
cargo test --features integration

WASM Tools and Channels

Building WASM Modules

If you modify channel or tool source code:

# Rebuild specific channel
./channels-src/telegram/build.sh

# Build all channels and the main binary
./scripts/build-all.sh

WASM Requirements

• Use the WASM Component Model
• Target wasm32-wasip2
• Declare capabilities in manifests
• Follow sandbox security guidelines

Pull Request Guidelines

PR Checklist

Before submitting, ensure:

• Code is formatted (cargo fmt)
• Linter passes (cargo clippy --all-features)
• Tests pass (cargo test)
• FEATURE_PARITY.md updated if applicable
• Documentation added/updated
• Commit messages are clear and descriptive
• PR description explains the change

PR Description Template

## Summary
Brief description of what this PR does.

## Changes
- List of specific changes
- Another change

## Related Issues
Fixes #123
Relates to #456

## Testing
How to test this change.

## Feature Parity
Updated FEATURE_PARITY.md: Yes/No

Code Review Process

1. Maintainers will review your PR
2. Address any feedback or requested changes
3. Once approved, a maintainer will merge your PR
4. Your contribution will be included in the next release

Getting Help

• GitHub Issues: Report bugs or request features
• Telegram: Join @ironclawAI
• Reddit: Visit r/ironclawAI
• Discussions: Use GitHub Discussions for questions

Code of Conduct

Be respectful and professional in all interactions. We’re building a welcoming community for everyone.

License

By contributing to IronClaw, you agree that your contributions will be licensed under either:

• Apache License, Version 2.0
• MIT License

at the user’s option, consistent with the project’s dual licensing.

Recognition

All contributors are recognized in the project. Thank you for making IronClaw better!