Edge Studio

Edge Studio is a set of tools and an application that allows you to create a local Ditto Database based on a database registered in the Ditto Portal and use the Ditto SDK to query information in the Ditto Edge Server, local Edge Server, or P2P with other devices sharing the same DatabaseId.

Key Features:

• Multi-app connection management with local storage
• Advanced per-database configuration: collection sync scopes and startup ALTER SYSTEM settings
• Real-time query execution with history and favorites
• Active subscriptions and observables management
• Connection status bar with transport-level statistics
• Presence viewer and peer management
• Disk usage monitoring and permissions health checking
• Import/export functionality

Download

Prebuilt apps are attached to each GitHub release.

Platform	Asset	Requirements
macOS	Ditto Edge Studio <version>.dmg	macOS 26.0+, Apple Silicon only
Android	EdgeStudio-<version>-arm64.apk	Android 9 (API 28)+, 64-bit ARM

macOS — open the DMG and drag the app to Applications. It's signed with a Developer ID certificate and notarized by Apple, so it opens normally. There is no Intel build: the Ditto SDK ships an arm64-only macOS framework.

Android — the APK is distributed directly rather than through the Play Store, so you'll need to sideload it. Download the APK, open it, and when prompted enable Settings → Install unknown apps for your browser or file manager, then tap Install. Android will show it as coming from an unverified developer; that's expected for a direct download.

Requirements

Ditto Portal Account:

• You need a Ditto Portal account. You can sign up for a free account at Ditto Portal.

App Requirements

• A Mac with MacOS 26.0 or higher installed (Apple Silicon)
• An iPad with OS 26.0 or higher installed
• An Android device or tablet running Android 9 (API 28) or higher, 64-bit ARM

Build REquirements

• Xcode 26.2 or higher installed
• SwiftLint Installed
• Swiftformat Installed
• Periphery Installed

Ditto SDK

This project uses Ditto SDK 5.1 (currently 5.1.0).

API Reference: https://software.ditto.live/cocoa/DittoSwift/5.1.0/api-reference/documentation/dittoswift/

Note: The SwiftUI app is only officially supports MacOS and iPadOS. While it will build and run on iOS, it has not been tested on iOS and there are known issues with the SwiftUI app on iOS.

Getting Started from Source

git clone <this-repo>
cd ditto-edge-studio/SwiftUI
open "Edge Debug Helper.xcodeproj"

Select the Edge Studio scheme and build/run for macOS or iPadOS. The Ditto SDK is fetched via Swift Package Manager, so the first build may take a few minutes. See docs/TESTING.md for how to run the test suites.

Development Tools

Edge Studio uses industry-standard code quality tools to maintain code health and detect unused code. These tools help catch issues early and keep the codebase clean.

Quick Start

# Install all tools
brew install swiftlint swiftformat peripheryapp/periphery/periphery

# Run quick quality check
swiftlint lint
swiftformat .

Installed Tools

Tool	Purpose	Integration	Documentation
SwiftFormat	Auto-formatting	Xcode build phase	Guide
SwiftLint	Style & quality rules	Xcode build phase	Guide
Periphery	Unused code detection	Manual (weekly)	Guide

Xcode Integration

Both SwiftFormat and SwiftLint are integrated into the build process:

• SwiftFormat runs first - automatically formats code
• SwiftLint runs second - shows violations as warnings in Xcode

To add both tools to your build:

1. Open project in Xcode
2. Target → Build Phases → "+" → New Run Script Phase (add 2 phases)
3. First: "SwiftFormat" phase (formats code)
4. Second: "SwiftLint" phase (checks code)
5. Add scripts (see CODE_QUALITY_GUIDE.md)

Configuration Files

All tools are configured via dotfiles in the project root:

• .periphery.yml - Periphery configuration
• .swiftlint.yml - SwiftLint rules and exclusions
• .swiftformat - SwiftFormat style rules

Common Commands

# SwiftLint
swiftlint lint              # Check violations
swiftlint lint --fix        # Auto-fix where possible

# SwiftFormat
swiftformat .               # Format all files
swiftformat --lint .        # Check formatting only

# Periphery
periphery scan --project "SwiftUI/Edge Debug Helper.xcodeproj" \
               --schemes "Edge Studio"

Recommended Workflow

1. Every build - SwiftFormat and SwiftLint run automatically (Xcode integration)
2. Weekly - Run Periphery to find unused code
3. Before releases - Run all tools with --strict flags

With build integration, you don't need to remember to format or lint - it happens automatically!

Complete Documentation

📖 See docs/CODE_QUALITY_GUIDE.md for:

• Detailed installation and configuration
• Xcode build phase setup
• Per-file rule overrides
• CI/CD integration examples
• Troubleshooting guide
• Best practices

Logging Framework

Edge Debug Helper uses CocoaLumberjack for file-based logging with user-viewable logs.

Installation (Required)

Add CocoaLumberjack via Swift Package Manager in Xcode:

1. File → Add Package Dependencies...
2. URL: https://github.com/CocoaLumberjack/CocoaLumberjack
3. Version: Latest (3.8.5+)

Usage

// Use the global Log accessor (import not needed)
Log.debug("Debug information")
Log.info("General information")
Log.warning("Non-critical issue")
Log.error("Failure or exception")

// DO NOT use print() - use Log instead

Features

• ✅ File-based: All logs written to files automatically
• ✅ Rotation: Keeps last 7 days, 5MB max per file
• ✅ User export: Future feature for GitHub issue attachments
• ✅ Performance: Asynchronous, doesn't block UI
• ✅ Location: ~/Library/Logs/io.ditto.EdgeStudio/

Retrieving Logs

// Get all log files
let logFiles = Log.getAllLogFiles()

// Get combined content
let content = Log.getCombinedLogs()

// Export to location
try Log.exportLogs(to: url)

Testing

Edge Debug Helper uses Swift Testing for comprehensive test coverage with mandatory testing requirements for all new code.

Quick Start

# Run all tests
xcodebuild test -project "SwiftUI/Edge Debug Helper.xcodeproj" \
                -scheme "Edge Studio" \
                -destination "platform=macOS,arch=arm64"

# Run with coverage report
./scripts/generate_coverage_report.sh

# View coverage dashboard
./scripts/coverage_dashboard.sh

Test Infrastructure

Target	Framework	Purpose	Coverage Goal
EdgeStudioUnitTests	Swift Testing	Fast, isolated unit tests	70%
EdgeStudioIntegrationTests	Swift Testing	Multi-component tests	50%
EdgeStudioUITests	XCTest	UI automation	30%

Testing Requirements

CRITICAL: All new code MUST have tests.

• ✅ Unit tests with Swift Testing (import Testing)
• ✅ 80%+ coverage on new code (minimum 50% overall)
• ✅ AAA pattern (Arrange-Act-Assert)
• ✅ Test isolation (uses separate database paths)
• ❌ No skipped tests
• ❌ No tests that touch production data

Current Status

Coverage measured 2026-08-21; test count measured 2026-08-23 (see docs/TESTING.md for details):

• Overall App-Target Coverage: 15.51% (target: 50%)
• SQLCipherService: 93.13% coverage ✅
• Total Tests: 761 Swift Testing tests (604 unit + 157 integration), plus 15 UI tests

Coverage Enforcement

There is no automated coverage gate (no pre-push hook). Coverage is measured manually via the scripts in scripts/ and enforced during code review.

Complete Documentation

📖 See docs/TESTING.md for:

• Complete testing guide (unit, integration, UI tests)
• Swift Testing framework tutorial
• Test isolation and sandboxing
• AAA pattern examples
• Coverage best practices
• Troubleshooting guide

AI Agent MCP Integration

Edge Studio embeds an MCP (Model Context Protocol) server that lets Codex, Claude Code, and other MCP clients query and manage your Ditto databases directly. No separate server binary is required.

Enable in Edge Studio

1. Open Edge Studio
2. Go to Edge Studio → Settings… (⌘,)
3. Toggle Enable MCP Server ON
4. A green dot confirms it's running on port 65269

Connect Codex

This repository includes .codex/config.toml, which Codex loads for trusted projects. Restart Codex after enabling the server, then verify it with /mcp in the Codex TUI or:

codex mcp list

To make the server available outside this repository, add it to your global Codex configuration using the MCP server UI in Codex or a [mcp_servers.ditto-edge-studio] entry in ~/.codex/config.toml with url = "http://localhost:65269/mcp".

Connect Claude Code

Option A — This repo (auto-discovered)

The .mcp.json at the root of this repo is picked up automatically by Claude Code when you work in this project. No extra steps.

Option B — Global (available in all projects)

claude mcp add ditto-edge-studio --transport sse http://localhost:65269/mcp

Verify it's connected:

claude mcp list
# ditto-edge-studio (sse) http://localhost:65269/mcp

What you can ask your agent

Once connected and with a database selected in Edge Studio:

• "List the collections in my active database and their document counts"
• "Run SELECT * FROM orders WHERE status = 'pending' LIMIT 5"
• "Run SELECT * FROM orders LIMIT 5 via the HTTP API"
• "Create an index on the users collection for the email field"
• "Show me the sync status and which transports are active"
• "Disable Bluetooth sync and show me the peer count"
• "Show me all connected peers and their SDK versions"
• "Stop sync, insert all documents from ~/Downloads/orders.json into the orders collection, then restart sync"

Available Tools

Tool	Description
execute_dql	Run any DQL query (SELECT, INSERT, UPDATE, EVICT); pass transport: "http" to route through the HTTP API instead of the local store
list_databases	List all configured databases
get_active_database	Details on the currently selected database
list_collections	Collections with document counts and indexes
list_indexes	Flat list of every index across all collections, with name, collection, and field paths
create_index	Index a collection field
drop_index	Remove an index by name
get_query_metrics	Recent query timing and EXPLAIN output (requires Metrics enabled in Settings)
get_sync_status	Connected peer count and transport config
configure_transport	Toggle Bluetooth, LAN, or AWDL transports
insert_documents_from_file	Insert a local JSON file (array of objects with _id) into a collection; file must be in ~/Downloads
set_sync	Start or stop sync for the active database
get_peers	Snapshot of all connected peers with device, OS, SDK version, and transport details
get_app_logs	Recent Edge Studio application log entries
get_ditto_logs	Recent Ditto SDK log entries

Note: All tools operate on the database currently selected in the Edge Studio UI. The MCP server stops automatically when Edge Studio quits.

For the full setup guide, troubleshooting, and security considerations see docs/MCP_SERVER.md.

---

⚠️ DISCLAIMER

THIS SOFTWARE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND.

This tool is NOT officially supported by Ditto or the author. It is provided as a community resource for development and debugging purposes only.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

By using this software, you acknowledge and agree that:

• There is no official support from Ditto or the author
• The software may contain bugs or incomplete features
• You use this software at your own risk
• No warranty of any kind is provided
• The authors are not liable for any damages resulting from use of this software

For official Ditto support and documentation, please visit Ditto Documentation.