# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this directory.

## Project Overview

This is the XMTP Android SDK - a Kotlin SDK that provides XMTP messaging functionality for Android applications. It is part of the [libxmtp monorepo](https://github.com/xmtp/libxmtp).

The SDK uses native Rust bindings from `bindings/mobile/` via UniFFI, providing high-performance cryptographic operations and MLS (Messaging Layer Security) support.

## Directory Structure

- **library/** - Main SDK source code
  - **src/main/java/org/xmtp/android/library/** - Core SDK implementation
  - **src/androidTest/** - Instrumented tests
  - **src/test/** - Unit tests
- **example/** - Example Android application
- **dev/** - Development scripts
  - **bindings** - Build native bindings via Nix
  - **build** - Build the full SDK

## Development Commands

### Environment Setup

```bash
# Enter Android development shell (from repo root)
nix develop .#android

# Or use direnv (if .envrc is allowed)
cd sdks/android && direnv allow
```

### Building

```bash
./dev/bindings              # Build native .so libraries + Kotlin bindings
./dev/build                 # Build the full SDK (includes bindings)
./gradlew build             # Build without rebuilding bindings
```

### Code Quality

```bash
./gradlew spotlessApply     # Format code
./gradlew spotlessCheck     # Check formatting
./gradlew :library:lintDebug  # Run Android lint
```

### Testing

```bash
./gradlew library:testDebug           # Run unit tests
./gradlew connectedCheck              # Run instrumented tests (requires emulator)
```

## Architecture

### Native Bindings

The SDK depends on native Rust code from `bindings/mobile/`:

- `.so` files are built for 4 Android ABIs: arm64-v8a, armeabi-v7a, x86_64, x86
- Kotlin bindings (`xmtpv3.kt`) are generated by UniFFI
- Bindings are built via Nix and output to `.build/bindings/`

The Gradle build includes these via `sourceSets` configuration in `library/build.gradle`.

### Key Components

- **Client** - Main XMTP client for authentication and conversation management
- **Conversation** - Base class for all conversation types
- **Group** - Group messaging with MLS
- **Dm** - Direct messaging
- **CodecRegistry** - Registry for content type codecs

## Important Notes

- Native bindings must be built before running tests or building the SDK
- The SDK supports XMTP V3 only (V2 deprecated as of May 2025)
- Minimum Android SDK: 23, Target SDK: 35
- Java version: 17
