lody-ios README

The project's README from github.com/LodyAI/lody-ios. As one markdown file: README.md.

Lody iOS Logo

Lody iOS

Native iOS Client · AI Collaboration & Session Companion for Mobile

Platform Swift 6.0 CRDT License: AGPL-3.0-only

https://github.com/user-attachments/assets/0bc0ab48-6f12-44e9-ae13-07af9c6b780d

Lody on iPad and iPhone


Origin and maintenance

This repository, LodyAI/lody-ios, is Lody’s iOS client. It began as Innei’s lody-ios, created by Innei and contributors, whose native application, LodyKit architecture, chat UI and protocol runtime form its foundation. The copy Lody developed in its monorepo has been merged back here with its history; see the mobile credits for provenance.

The Lody monorepo checks this repository out as the apps/mobile/ios submodule. Develop and build it from there: the build reads the shared apps/mobile/backend-config.mjs and apps/mobile/shared/markdown-repair, and Android snapshots packages/cloud-runtime from it. Commit iOS changes here, then update the submodule pointer in Lody.

The source is under active development. Upstream TestFlight links and workflows refer to the upstream distribution, not a release of this repository.

Overview

Lody iOS is a native open-source client crafted for iPhone, providing a lightweight and secure bridge between remote Lody services and local workspaces.

The application UI and native state run in Swift and UIKit. LodyKit owns navigation, screens, authentication, catalog projections and durable sends. A Swift-managed offscreen WebView runs the bundled Loro/Flock protocol engine; React Native, Expo, Hermes and Metro are no longer app dependencies.


Agent settings

Settings → Agent follows the Web mobile provider page: select a machine in a native sheet, then manage that machine’s providers and setup requests. Forms support provider names and instructions, custom commands and arguments, preset credentials and endpoints, write-only environment patches, Codex authentication profiles, runtime paths, and capability-driven title options. Save and test persists changes before probing a persisted agent; newly queued setups continue through setup status and authentication. Managed-runtime status/install and Pi extension discovery are also available while creating a supported provider. Saved providers expose a separate usage refresh; quota and pace displays remain sourced from the catalog usage projection.

ACP sign-in supports method selection, browser authorization, user codes, consent, and typed input requests through the public machine RPC. Pending setups awaiting authentication expose the same flow. Browser links stay disabled until any required consent is accepted by the machine. Auth events are scoped to the active flow, and provider-change events refresh and merge only the affected machine. Credentials stay on the selected machine; list data and local caches exclude environment values. Existing keys offer Keep, Replace, or Remove, and submitted secrets are cleared. Ownership, machine capabilities, offline state, and revision checks gate writes. Sorbet connection and endpoint-store management still require native encrypted feature transport and show their specific unavailable capability.

agents-settings, agents-presets, agents-pi, and agents-auth-methods are independent offline UI verification cases for provider CRUD and failure recovery, preset/secret preservation, Pi runtime patches, and method-selection flow identity plus consent-before-browser behavior. They use production controllers with synthetic service boundaries and perform no external sign-in.

Roles remain a separate setting. Settings home has no Machines entry; machine details and execution-machine selectors elsewhere remain available.

How this was built

Lody iOS started as a one-day prototype and became a usable TestFlight client in about a week, driven by coding agents under tight product constraints: iOS only, one native kit module, system UI when React Native cannot meet HIG, and an offscreen WebView for Flock/Loro because official Node/CRDT packages do not bundle in Metro.

The full first-person write-up is Prototype in a Day, Shipped in a Week: Building Lody iOS in Live.

What that week actually looked like:


Features

Authentic Apple HIG Native Experience

High-Performance Native Streaming Chat

The iOS app uses fixed Ink accents in both light and dark appearances, including Send and Stop; conversation activity/status colors remain unchanged. Preferences contains the app-icon picker. Settings has no Appearance, MCP servers, or Memory pages; dark canvases use fixed soft backgrounds. Process status labels use the same regular type as their duration, without a leading loading icon. The final visible command group shimmers while its turn runs, even after its tools complete or record a duration, and when hidden thinking calls follow it. User bubbles collapse to six measured lines. Agent footer icons align with the message edge: Copy, Info and Fork, 32 pt apart, followed by time 12 pt after the last glyph. The whole opened-chats count row toggles its children, while the opener above opens the conversation. Normal replies use 16 pt body text and 18 pt semibold headings; thoughts retain 15 pt body text and 17 pt headings, with Dynamic Type scaling. MCP creation and reply receipts use compact conversation-list rows from the public operation payloads: provider marks, single-line titles, trailing status and curved child connectors, without filled card backgrounds. Consecutive creation receipts share a five-row expandable group; cards retain the creating turn's status and refresh titles and provider marks from the live catalog. Progress-linked successes are hidden, while errors, cancellations and uncertain or incomplete result batches remain visible. Reply cards open the saved Markdown reply; shortened receipts say so, and a separate button opens the exact conversation or Tab. Agent Role and schedule proposals (lody_agent_role_create / _update, lody_schedule_propose) render as ChatProposalCell cards from the runtime's proposal projection: the proposed fields (Before/After for an update, the rule in ScheduleFormat words), then Dismiss and Save / Create through decideProposal. Only the requesting member decides a Role proposal; a decided proposal is a receipt, and a created schedule opens Schedules. Failures stay on the card for an explicit retry. See the decision. Files the Agent shares (lody_upload_files) use ChatFileCardCell and open like attachments. The related-conversations icon above the composer opens a live native tree, with each conversation and its contained Tabs sharing one horizontally scrolling row. Scrollbars stay hidden; edge fades indicate more targets in either direction. Only opened-by descendants receive indentation and curved rails. Adjacent operation receipts for the same conversation also share a horizontal row, retaining each target’s independent full-reply and navigation actions. The current exact target uses a subtle background and accessibility selection; layout conveys containment without Tab/current/directory labels. Status icons replace redundant visible status words while keeping accessible descriptions, reply excerpts and error notices. Running rows use the Home working-grid indicator. Missing precise openers never fall back to provenance-only root IDs. Archived and side-panel sessions are excluded; closed Tabs appear only when current. The tree does not change archive ownership or read additional transcripts.

The workspace switcher is Chrome/WorkspaceSwitcherPanel, a popover anchored to the capsule that never adapts into a sheet. A UIMenu wraps long titles onto several lines and offers no fade, so the panel draws its own menu-style rows: leading checkmark, circular avatar, and the name on one line that fades out at the trailing edge (LodyFadingLabel, mirrored for right-to-left) instead of wrapping or showing an ellipsis. Rows keep full names and the selected trait for VoiceOver; up to eight rows show before the list scrolls, and the width stays between 200 and 260 pt within the window. Selecting the current workspace is a no-op; catalog changes refresh the open panel. The account email heads the panel, projected explicitly through the session source and chrome model. Empty email removes the heading; synthetic sources never fall back to the live account. Workspace management stays in Settings.

Conversation Back, title/machine, Tabs and More controls belong to the page, so UIKit’s interactive pop moves them with its content instead of separately animating the system back circle. The transparent header registers its controls with UIKit through UIScrollEdgeElementContainerInteraction, retaining the transcript’s native .soft top-edge blur. A noninteractive 55% semantic canvas tint protects the title and machine subtitle, fading to transparent over 32 pt below the header rather than adding an opaque chrome material. The transcript scrolls underneath; content/find insets keep initial content and search below the controls. The shell hides native navigation for conversations; iPhone pages opened from a Home tab carry their native bar inside the page (LodyPageStackHost); other detail pages retain the shell's native bars. Back uses the existing navigation/split owner, and controls retain native glass styling and accessibility labels. The book-layout conversation list popover anchors to the visible page sidebar button and its bounds; native navigation-bar controls retain their bar-item anchors.

Conversation titles use 16 pt semibold system text, fading at the trailing edge only on overflow rather than inserting an ellipsis. VoiceOver retains the full title. User bubbles fill the available reading width beside the avatar; long-press offers Copy, plus Edit for the last eligible user message, without inline action buttons. Delivery status appears below the complete user message, including attachments, and stays there during history takeover and confirmation dismissal. Below the conversation title, secondary-gray machine text starts with a presence icon; tapping the header opens the panel with name and presence, owner avatar and name, then private/shared visibility. Visibility comes from the public machine-registration query on opening; unavailable data is shown as unknown, never inferred as private. The bottom machine capsule is omitted. The trailing Tabs button appears only with other open Tabs. Its corner dot indicates unread output in other Tabs, respecting local visits; activity remains on each row in the expanded panel. More retains closed-Tab recovery and New current working directory conversation, using the existing create-Tab operation. Chat inline code matches the body size in a monospaced face. Prose blocks use secondary-label grey (links use web’s muted light/dark blue); fenced code retains its own sizing and colours. With MarkdownView's shared code colour, a list or quote containing a fence keeps its original code colours throughout that block.

In Chats Home (compact, and the iPad / iPhone Duo split column), project grouping reveals an opaque project index while scrolling, over the list. Tap a logo or scrub the rail to jump through committed rendered sections, including Pinned and unassigned chats. Only the visible 56 pt rail intercepts touches; no index recognizer is installed on rows. It stays visible through dragging/deceleration and for 0.8 seconds after scrolling or scrubbing ends. Renewed interaction invalidates pending dismissal. Snapshot replacement, backgrounding, detachment and size changes cancel the interaction. Search and time/status groupings retain their existing lists. VoiceOver adjustment follows rendered group order. Repository identities flow from catalog repoFullName through the root row to cached GitHub owner avatars, displayed in dedicated 24 pt image views at full opacity; projects without artwork use one initial. Targets are 48 × 48 pt with 48 pt centre spacing, 12 pt capsule end padding and an 8 pt trailing screen inset. Dense rails show a bounded set of evenly spaced landmarks without shrinking targets or artwork. Landmarks stay fixed during a gesture; selection highlights a landmark only when that destination is selected. Scrubbing anchors to the tapped destination with an 8 pt movement allowance, then maps each direction to the rail endpoint; small finger drift does not jump to a different proportional destination. Scrubbing and VoiceOver still reach every project. Pinned and unassigned groups keep their symbols. The opaque semantic background follows light/dark appearance. Entrance and exit use a short 12 pt slide and fade, with full opacity at rest. Dismissal disables touch targets immediately; Reduce Motion uses immediate visibility changes. verify:native --case chat-list-scroll covers hit bounds, direct navigation, 48 pt target spacing, stable dense landmark taps, complete scrub/VoiceOver reach, deterministic linger cancellation and cached artwork.

Native Schedules

Schedules uses the Chats list layout, with task and scheduled-message rows grouped by Needs attention, Active, Paused and Ended. Each row separates its title and status from the recurrence and execution context; search filters by title.

The editor places current status and quick actions above separate Task, When and Run with cards. Weekdays and month days are directly selectable; date and time use native pickers in the computer's time zone. Owners can run, pause or resume supported tasks and open the last conversation. Teammates' tasks and scheduled messages retain their existing read-only rules, and deletion requires confirmation.

Successful list reads persist as bounded SQLite display snapshots per account and workspace. Cold starts restore the saved list before refreshing from the runtime; failed reads retain it. Logout clears these snapshots and fences late writes. Optimistic states are never persisted, and cached rows do not authorize mutations. Opened details and editor choices stay in memory within the current Home page. Returning to a loaded editor shows its snapshot immediately while detail and choices refresh independently; failed refreshes retain existing content, and refreshes preserve unsaved edits. Cached details can be edited immediately; Save waits for fresh detail validation and blocks when the refresh detects changed remote content. Pause/resume preview their state immediately and roll back on failure, with the existing unknown-outcome warning when a reply is lost. Pending commands fence older reads; account/workspace changes discard snapshots and late responses. The runtime still re-reads current data before mutations. A workspace without a saved list shows the loading state until its first successful read.

Project groups

Project groups are desktop's multi-repository projects: one project whose members are GitHub repositories or local folders. Mobile shows them but does not create or edit them yet.

Code Diffs & Workspace File Browsing

Live Preview & Simulator Streaming

Offscreen WASM CRDT Data Sync Engine

Security First & Hardware Isolation


Architecture

flowchart TB
    App[UIKit AppDelegate / SceneDelegate] --> Owner[LodyApplication]
    Owner --> Shell[LodyShell / HomeController]
    Shell --> Pages[Native feature controllers]
    Owner --> State[AuthSession / CatalogSession / OutboxSession]
    Pages --> State
    State --> Runtime[Swift DataRuntime / watchdog]
    Runtime --> WebView[Bundled WKWebView: Loro / Flock / Streams]
    WebView --> Cloud[Lody Cloud / Machine RPC]
    State --> SQLite[SQLite projections / durable outbox]
    State --> Keychain[Keychain credentials]

Directory Structure

The Xcode navigator includes app sources, extensions, runtime inputs, scripts and verification files. Shared Extension Sources groups the LodyKit files compiled by extensions; their single source of truth remains the local Swift package. Generated runtime assets and build configuration live under .generated.

apps/ios/Lody.xcodeproj              # Generated Xcode project
apps/ios/project.yml                # XcodeGen: app, extensions and verify hosts
apps/ios/App/                       # UIKit entry, plist, entitlements and app assets
apps/ios/App/Resources/             # Images, file icons and dependency notices
apps/ios/Extensions/                # Share and notification service
apps/ios/.generated/                # Generated plist, XcodeGen input and runtime assets
apps/ios/runtime/decoder/           # Browser-safe decoding adapter
apps/ios/scripts/                   # Asset generation and source checks
apps/ios/verification/kit/          # Native behavior checks
apps/ios/verification/ui/           # Offline UI verification
apps/ios/tests/                     # Protocol and tooling Node tests
packages/LodyKit/Package.swift      # LodyKit library, dependencies and Metal resources
packages/LodyKit/Sources/LodyKit/    # UIKit UI, native state and coordinators
packages/LodyKit/Sources/LodyKit/Resources/ # Native String Catalog
packages/LodyKit/DataChannel/        # Pinned native transport build
packages/cloud-runtime/              # Bundled browser-safe protocol and contract
packages/lody-core/                  # Swift wire types and routing policies
packages/chat-kit/                   # Native chat core
packages/lexical-swift/              # Native editor

Development & Build

Prerequisites

Getting Started

  1. Clone the repository and install JavaScript dependencies:

    # From the Lody repository root:
    git submodule update --init --recursive apps/mobile/ios/packages/chat-kit
    cd apps/mobile/ios
    corepack pnpm install --frozen-lockfile
    
  2. Generate the native project and open Xcode:

    pnpm ios
    

    pnpm ios builds bundled protocol assets and the native data channel library, then generates apps/ios/Lody.xcodeproj with XcodeGen. Xcode resolves Swift packages directly. Select a simulator and Run. pnpm start opens the existing project. App, extensions and offline verification hosts come from project.yml; rerun pnpm prebuild after changing those sources. LodyKit is a local Swift package in packages/LodyKit; SwiftPM discovers its sources automatically and bundles its Metal shaders.

  3. Update native assets:

    After editing packages/cloud-runtime or apps/ios/runtime/decoder, run:

    pnpm bundle
    

Quality Checks & Testing

pnpm check            # TypeScript, locale catalogs, generated license notices, Prettier
pnpm test             # Protocol tests and Simulator tooling tests
pnpm bundle           # Build bundled WebView protocol assets and native catalogs
pnpm licenses:build   # Regenerate the in-app notices after dependency changes

Offline UI Verification

UI baselines run without login, user credentials, cloud access, or a connected machine: the runner launches with --ui-verify and injects deterministic native data at the Auth/Catalog boundary, and every case starts from the development-only Debug page.

pnpm verify:simulator --name '<current verify>' -- <command>   # Lease a Lody * Verify Simulator
pnpm verify:native                                             # Swift behavior checks
pnpm verify:ui --app /absolute/path/to/Lody.app                # Offline UI baselines
pnpm verify:ui --suite core --app /absolute/path/to/Lody.app  # PR core paths, Release app

The runner captures screenshots for visual states and video for temporal behavior; missing scenes and timeouts fail the run. See apps/ios/verification/ui/README.md for the case inventory and Simulator leasing rules.

Releases

The nested .github/workflows/ files are retained upstream references and do not run from this subdirectory. This import does not configure signing, TestFlight publishing, or an official mobile release pipeline.


License

Lody iOS is released under the GNU Affero General Public License v3.0 (AGPL-3.0-only). You may use, modify, and distribute it, including commercially, provided that derivative works and network-served modifications stay under the same license and their source stays available to users.

Bundled third-party libraries and assets keep their own licenses. The full list and license texts are available in the app under Settings → Open Source Licenses. The notices are generated from the production dependency closure by pnpm licenses:build and verified in CI by pnpm check.


Acknowledgements

Lody iOS is made possible thanks to these open-source projects and creators:

Backend configuration

See native backend configuration for the optional ../.env.local, production defaults, public TLS endpoints and isolated local stores.

Native canvas appearance

App-owned dark backgrounds are fixed soft #111113. LodyTint provides plain, grouped and opaque canvases, while LodyAppearance uses the same dark base for bgBase and bgGrouped. Light backgrounds retain their existing semantics. Camera and simulator media surfaces use the fixed dark color in both themes; launch uses the matching dynamic CanvasBackground asset. The app icon is available under Settings → Preferences. There is no Appearance page; legacy darkBackground values are ignored, not migrated. This supersedes the optional pure-black background described in the historical Home design and settings migration documents. Masks, scrims, shadows, media content and foreground colors remain unchanged. The native design check tests legacy values, both themes and increased contrast, including text readability.

Conversation More → Archive returns to Home immediately while the write continues. Success is silent; a failed write shows a warning only while its original Home, account and workspace remain active. Unarchive stays on the conversation. The existing native session suite can isolate these menu actions with LODY_VERIFY_SESSION_ARCHIVE_ONLY=1 pnpm verify:ui --case session-native --require-video --app /absolute/path/to/Lody.app. The session-info-bar native check explicitly holds and releases archive writes to verify immediate navigation, silent delayed success and scoped delayed failure.

lody-ios (LodyAI/lody-ios)

Searching Database…

What is this?Lody iOS is an independent, community-maintained iOS client for Lody, providing native chat, session management, and coding-agent collaboration on iPhone.
Is this the official Lody app, or a separate project?It is unofficial — a third-party, community-built app, not affiliated with or supported by the official Lody team; built with React Native plus native Swift/CoreText modules.
How do I install it on my iPhone?Join the TestFlight beta — the README provides a public invite link so you can install the current build directly from TestFlight.
Is this stable enough to rely on for real work?No — the README warns it iterates quickly, so APIs, sync behavior and UI can change without notice, builds can be unstable, and updates may even break existing chat sessions.
What is Lody itself?From the README, Lody is a chat-based platform organized around sessions and coding-agent collaboration; this app is an independent native iPhone client that talks to it, since Lody itself isn't described in detail in this repository.
How does data stay in sync across devices?It uses Loro, a high-performance CRDT, for state synchronization, as credited in the acknowledgements section of the README.
Can I test the UI without logging in or using a real device?Yes — offline UI verification injects deterministic data at the Auth/Catalog boundary and runs from a development-only Debug page, so baselines work without login, credentials, or cloud access.
What powers the native chat rendering?The message view draws on FlowDown for its design, and renders Markdown through Litext (a CoreText rich-text engine) and MarkdownView for typography.
Creator
LodyAI
Size
55.5 MB
Stars
532
Updated
CommitNov 18
Age
2mo
Commits · 90 Days