diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 0000000..6535198
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(cargo build:*)",
+      "Bash(diesel migration generate:*)"
+    ],
+    "deny": []
+  }
+}
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c95481c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Build & Run
+```bash
+# Build all workspace members
+cargo build
+
+# Build specific package
+cargo build -p kordophone
+cargo build -p kordophone-db  
+cargo build -p kordophoned
+cargo build -p kpcli
+
+# Run daemon
+cargo run --bin kordophoned
+
+# Run CLI tool
+cargo run --bin kpcli -- --help
+```
+
+### Testing
+```bash
+# Run all tests
+cargo test
+
+# Run tests for specific package
+cargo test -p kordophone
+cargo test -p kordophone-db
+```
+
+### Database Operations
+```bash
+# Database migrations (from kordophone-db directory)
+cd kordophone-db
+diesel migration run
+diesel migration revert
+```
+
+## Architecture
+
+This is a Rust workspace with 4 main packages forming a messaging client/daemon system:
+
+### Core Components
+
+- **kordophone**: Core library providing API client and models for messaging operations
+- **kordophone-db**: Database layer using Diesel ORM with SQLite, handles conversations/messages storage
+- **kordophoned**: Background daemon that syncs with messaging server and exposes D-Bus interface
+- **kpcli**: Command-line interface for interacting with daemon and performing database operations
+
+### Key Architecture Patterns
+
+- **D-Bus IPC**: Daemon exposes functionality via D-Bus at `net.buzzert.kordophonecd`
+- **Event-driven**: Daemon uses async channels for internal communication and D-Bus signals for external notifications
+- **Repository Pattern**: Database access abstracted through repository layer in kordophone-db
+- **Workspace Dependencies**: Packages depend on each other (kordophoned uses both kordophone and kordophone-db)
+
+### Data Flow
+
+1. kpcli/external clients interact with kordophoned via D-Bus
+2. kordophoned manages HTTP API client connections to messaging server
+3. Background sync processes fetch data and store via kordophone-db repository
+4. D-Bus signals notify clients of data updates (ConversationsUpdated, MessagesUpdated)
+
+### Important Files
+
+- `kordophone-db/diesel.toml`: Database configuration
+- `kordophone-db/migrations/`: Database schema definitions
+- `kordophoned/include/net.buzzert.kordophonecd.Server.xml`: D-Bus interface definition
+- `*/build.rs`: D-Bus code generation for dbus-crossroads interfaces
+
+### Settings Storage
+
+Settings are persisted in SQLite database using a key-value store approach. Access via `Settings` struct in kordophone-db.
\ No newline at end of file