> ## 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.

# 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](https://rustup.rs)
* Git for version control
* A GitHub account

See [Building from Source](/development/building) for detailed setup instructions.

## Development Workflow

### 1. Fork and Clone

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
git add .
git commit -m "Add feature: brief description"
```

### 5. Push and Create PR

```bash theme={null}
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:

```diff theme={null}
| 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:

```bash theme={null}
cargo fmt
```

### Linting

Code should pass clippy without warnings:

```bash theme={null}
cargo clippy --all --benches --tests --examples --all-features
```

### Testing

Add tests for new functionality:

```bash theme={null}
# 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](/development/testing) 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](https://rust-lang.github.io/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:

```rust theme={null}
/// 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:

```rust theme={null}
#[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):

```bash theme={null}
cargo test
```

For PostgreSQL integration tests:

```bash theme={null}
# 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:

```bash theme={null}
# 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

```markdown theme={null}
## 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](https://t.me/ironclawAI)
* **Reddit**: Visit [r/ironclawAI](https://www.reddit.com/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!