Luego

A minimal read-it-later app for iPhone and iPad, with offline access to previously fetched articles.

Download on the App Store or Join Beta on TestFlight.

Architecture

Luego uses SwiftUI and Observation, with services organized by feature and dependencies wired through DIContainer. Articles are stored locally with GRDB/SQLite and synchronized through CKSyncEngine with a CloudKit private database. See ARCHITECTURE.md for the data flows and AGENTS.md for contribution rules.

Features

• Article saving: Add a URL in the app or queue it through the share extension for import when the app is active.
• Content extraction: Parse articles locally with a downloaded parser SDK, with API fallback.
• Offline reading: Read previously fetched content with saved reading position and Markdown rendering.
• Reading lists: Favorite and archive articles, with local SQLite storage and iCloud sync.
• Discovery: Explore articles from Kagi Small Web and Blogroll.
• Import and export: Transfer article URLs as plain text.

Requirements

• iOS 26.0+ or iPadOS 26.0+
• Xcode 26.0+
• The project uses Swift 5 language mode with complete strict concurrency checking.

Installation

1. Clone the Repository

git clone https://github.com/quietform/Luego.git
cd Luego

2. Open in Xcode

open Luego.xcodeproj

3. Configure Signing

Before building, you need to configure code signing:

1. Select the Luego project in the navigator
2. Select the Luego target
3. Go to Signing & Capabilities tab
4. Select your Team from the dropdown
5. Repeat for the LuegoShareExtension target

Bundle identifiers and display names are configured per build configuration in Configuration/. If using your own identifiers, update both targets, their App Group entitlements, the App Group identifiers in SharedStorage and LegacySwiftDataArticleDataSource, and the CloudKit container in the app entitlements and AppConfiguration together. The app uses iCloud.com.esoxjem.Luego; both targets share group.com.esoxjem.Luego for queued URLs.

Developer CLI

Run these commands from the repository root. Use xcodebuildmcp instead of calling xcodebuild directly. .xcodebuildmcp/config.yaml configures the Luego project and scheme, Debug configuration, and iPhone 17 simulator.

xcodebuildmcp simulator build --use-latest-os
xcodebuildmcp simulator build-and-run --use-latest-os
xcodebuildmcp simulator test --scheme LuegoTests --use-latest-os --json '{"extraArgs":["-parallel-testing-enabled","NO"]}'
xcodebuildmcp simulator list
xcodebuildmcp simulator screenshot --simulator-id <uuid>
xcodebuildmcp simulator snapshot-ui --simulator-id <uuid>

The LuegoTests scheme runs service and persistence tests with isolated storage, without launching the app or contacting CloudKit. Build and run on the relevant iPhone and iPad simulators, then verify behavior with logs or screenshots as described in AGENTS.md.