Contributing to IronClaw

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

​

Welcome Contributors

​

Getting Started

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

​

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

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

​

3. Make Your Changes

# Format code
cargo fmt

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

# Run tests
cargo test

​

4. Commit Your Changes

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

​

5. Push and Create PR

git push origin feature/your-feature-name

• 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

​

When to Update FEATURE_PARITY.md

• 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

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

​

Code Quality Standards

​

Formatting

cargo fmt

​

Linting

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

​

Testing

# Run all tests
cargo test

# Run specific test
cargo test test_name

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

​

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

/// 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

​

Security Considerations

​

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

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

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

​

Integration Tests

​

Database Tests

cargo test

# Create test database
createdb ironclaw_test

# Run integration tests
cargo test --features integration

​

WASM Tools and Channels

​

Building WASM Modules

# 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

• 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

​

License

• Apache License, Version 2.0
• MIT License

​

Recognition