Mova

A mobile client for org-agenda-api - access and manage your Emacs org-mode tasks from Android and iOS.

Overview

Mova is a React Native/Expo application that connects to an org-agenda-api server, providing a native mobile interface for:

• Viewing your daily agenda with scheduled items and deadlines
• Capturing new tasks using org-mode capture templates
• Searching across all your TODO items
• Running custom agenda views
• Receiving notifications for upcoming tasks

Relationship to org-agenda-api

Mova is the mobile frontend for org-agenda-api, a JSON HTTP API that exposes org-mode data from GNU Emacs. The architecture:

flowchart TB
    subgraph Docker["Docker Container"]
        nginx["nginx<br/>(HTTP Basic Auth)"]
        subgraph Emacs
            httpd["simple-httpd<br/>(HTTP server)"]
            api["org-agenda-api<br/>(elisp)"]
            org["org-mode"]
            httpd --> api --> org
        end
        repo["Git Repository<br/>(.org files on disk)"]
        sync["git-sync-rs"]
        nginx --> httpd
        org <--> repo
        sync <--> repo
    end
    remote["Remote Git"]
    mova["Mova<br/>(this app)"]

    sync <--> remote
    mova <-->|HTTP/JSON| nginx

Loading

• nginx handles HTTP Basic Auth and proxies requests to Emacs
• simple-httpd provides the HTTP server functionality within Emacs
• org-agenda-api is an elisp package that runs inside Emacs, translating org-mode data into JSON HTTP responses
• org-mode reads and writes .org files from the git repository on disk
• git-sync-rs keeps the local git repository synchronized with a remote
• Mova connects to nginx via HTTP Basic Auth to provide a native mobile experience

You need a running org-agenda-api instance for Mova to connect to. See the org-agenda-api README for setup instructions.

Features

Agenda View

• Daily agenda with date navigation
• Shows scheduled items, deadlines, and overdue tasks
• Pull-to-refresh synchronization
• Inline task completion and editing

Capture

• Template-based task capture using your org-mode capture templates
• Dynamic form fields (text, dates, tags) defined by templates
• Priority and TODO state selection
• Scheduled/deadline date pickers
• Remembers your last-used template

Search

• Full-text search across all TODO items
• Searches title, tags, and TODO state
• Real-time filtering

Custom Views

• Access your custom org-agenda commands
• Dynamic view rendering from server-defined views

Android Widget

• Quick Capture widget for home screen
• Capture tasks without opening the app
• Configurable template per widget instance

Notifications

• Background sync for upcoming tasks
• Configurable notification intervals
• Scheduled and deadline reminders

Getting Started

Prerequisites

• Node.js 18+
• Yarn or npm
• A running org-agenda-api server
• For development: Android Studio (Android) or Xcode (iOS)

Installation

# Clone the repository
git clone https://github.com/colonelpanic8/mova
cd mova

# Install dependencies
yarn install

# Start the development server
yarn start

Running the App

# Android
yarn android

# iOS
yarn ios

# Or use Expo Go for quick testing
npx expo start

Connecting to org-agenda-api

1. Launch Mova
2. Enter your org-agenda-api server URL (e.g., https://your-server.com)
3. Enter your username and password
4. Tap Login

Development

Project Structure

mova/
├── app/                    # Expo Router screens
│   ├── (tabs)/             # Main tab navigation
│   │   ├── index.tsx       # Agenda screen
│   │   ├── capture.tsx     # Capture screen
│   │   ├── search.tsx      # Search screen
│   │   ├── habits.tsx      # Habits screen
│   │   ├── views.tsx       # Custom views
│   │   └── settings/       # Settings screens
│   ├── edit.tsx            # Todo editor
│   └── login.tsx           # Login screen
├── services/               # API client, query cache, background tasks
│   ├── api.ts              # org-agenda-api client
│   ├── queryClient.ts      # TanStack Query client + offline persistence
│   ├── captureOutbox.ts    # Durable offline capture queue
│   ├── backgroundSync.ts   # Background task registration
│   └── notifications.ts    # Local notifications
├── hooks/                  # Query hooks (useAgendaData, queryKeys), mutations
├── components/             # Reusable UI (agenda/, capture/, todoForm/, todoEditing/)
├── context/                # React context providers (auth, settings, filters)
├── widgets/                # Android home-screen widget (JS side)
├── android/wear/           # Wear OS companion app (Kotlin)
└── tests/                  # Jest unit/integration/component tests

Commands

yarn start          # Start Expo dev server
yarn android        # Run on Android
yarn ios            # Run on iOS
yarn test           # Run Jest tests
yarn typecheck      # TypeScript validation
yarn lint           # ESLint check
yarn e2e:android    # Run Detox E2E tests

Testing

# Unit tests
yarn test

# E2E tests (requires Android emulator)
yarn e2e:build:android
yarn e2e:android

Tech Stack

• React Native + Expo - Cross-platform mobile framework
• Expo Router - File-based navigation
• React Native Paper - Material Design 3 components
• TanStack Query - Server-state caching, invalidation, and offline persistence (queries are keyed per server identity and persisted to AsyncStorage for offline launches)
• TypeScript - Type safety
• Jest + Detox - Testing

Note: the home-screen widget, quick-capture activity, and Wear OS companion app are Android-only; iOS currently has no counterpart for these capture surfaces.

The Wear OS companion also provides a Mova Quick Capture Tile. Add it from the watch’s tile picker to launch voice capture directly by swiping from the watch face and tapping Capture.

Configuration

Capture Templates

Capture templates are defined in your Emacs org-mode configuration and exposed via the org-agenda-api /capture-templates endpoint. Mova automatically fetches and renders forms based on your template definitions.

Example template structure from org-agenda-api:

{
  "todo": {
    "name": "Todo",
    "prompts": [
      { "name": "title", "type": "string", "required": true },
      { "name": "scheduled", "type": "date", "required": false },
      { "name": "tags", "type": "tags", "required": false }
    ]
  }
}

Notifications

Configure notification preferences in Settings:

• Enable/disable notifications
• Set reminder intervals (e.g., 15 minutes before)
• Background sync frequency (default: 15 minutes)

License

GPL v3