ClaimSolo

ClaimSolo is a private, personal flight-claims assistant for assessing, preparing, documenting, and tracking compensation claims for one family.

It is inspired by the clarity of commercial flight-claims services, but it is not affiliated with AirHelp and does not copy its branding, content, or proprietary design.

ClaimSolo's public landing page. The illustrative case shown is fictional.

Implemented capabilities

• Deterministic, versioned EC261 and UK261 eligibility assessments
• Indicative fixed-compensation estimates with assumptions and uncertainty kept visible
• Single flights, protected connections, and self-transfer journeys
• Global airport lookup with IATA, city, and airport-name autocomplete, route distance calculation, and airport metadata
• Editable, reusable family passenger profiles
• Editable claim facts and flight segments without losing evidence or history
• Evidence, receipts, correspondence, expenses, deadlines, and claim timelines
• Portable .ics deadline reminders for Apple Calendar, Google Calendar, and Outlook, plus optional native macOS background notifications
• Human-readable delays in hours and minutes
• English complaint-letter drafts for journeys and individual bookings
• Claim and booking statuses from draft through submission, escalation, payment, or closure
• Five-step claim progress from preparation through airline, authority/ADR, and court escalation
• Static in-app process guide explaining the practical route from evidence to airline, authority/ADR, and court
• Elapsed-day, response-window, recommended-submission, and mapped limitation guidance with source links
• 59 maintained airline profiles mapped to reviewed official compensation, disruption, passenger-rights, or customer-service routes
• 33 national authority profiles, including ANAC, ENAC, and other EC261/UK261 enforcement bodies
• Timing-sensitive form guidance, including Ryanair's published 24–96 hour review window
• Booking-level work items with their own assessment, readiness checklist, letter, status, and submission history
• Per-booking evidence assignment and submission records with confirmation references, linked receipts, and follow-up dates
• Recoverable claim archiving and an archived-claims view
• Local SQLite persistence and a private local evidence folder
• ZIP backup export and validated restore containing the database, manifest, and uploaded evidence; restore first creates a local safety snapshot

Product scope

ClaimSolo is a local web application with a React and TypeScript frontend, a lightweight Express backend, and SQLite storage. Flight details are entered manually, so the application does not require an external flight-data API.

The app is intended only for personal and family use. It has no customer accounts, payment flows, service fees, marketing funnel, or automatic claim submission.

Manual and calculated workflow deadlines offer an .ics download containing reminders one day before and on the due date. On macOS, Settings can also install a per-user launchd LaunchAgent that checks manual and calculated deadlines every day at 09:00 local time and posts due-day notifications through Notification Center. It runs even when the browser and ClaimSolo server are closed; Apple documents that a missed StartCalendarInterval job runs after the Mac wakes. The helper reads only the selected local ClaimSolo data directory and makes no network request.

Use Settings → Calendar and macOS notifications → Install background reminders to opt in. The same panel can send a test notification, show the local LaunchAgent and log paths, or remove the background job completely. Notification visibility still follows macOS Notification Center, Focus, lock-screen, and preview settings.

A later phase may package the app as an installable desktop application using Tauri.

Current implementation

The working local MVP is in this repository:

• apps/client: English-only React/Vite interface
• apps/server: local Express API, uploads, backup export, and SQLite persistence
• packages/domain: deterministic EC261/UK261 assessment rules, airport-distance calculations, 59 airline submission profiles, and 33 national authority profiles

The private dashboard populated with fictional demo data. No personal claim information is shown.

The original approved implementation contract is in claimsolo-personal-one-shot-prompt.md. The current build intentionally keeps the product English-only, as requested, while preserving the local-first and privacy constraints.

Booking-level work is stored beneath the parent journey. This is especially important for self-transfers: a separate booking is not automatically treated as a protected connection, and its evidence and airline correspondence can be tracked independently.

Run locally

Prerequisite: Node.js 24.x. The local server uses Node's built-in SQLite support, so no native SQLite addon or cloud database is required.

npm is the command runner installed with Node.js. Run these commands in the ClaimSolo repository folder; none of them uploads claim data to an online service.

git clone https://github.com/codecube/ClaimSolo.git
cd ClaimSolo
npm install
npm run db:migrate
npm run dev

Open http://127.0.0.1:5173. The API runs on http://127.0.0.1:4174. After npm run build, npm start serves the built interface and API from http://127.0.0.1:4174.

For quick reference:

• npm install installs the application dependencies, normally only needed after cloning or pulling changes.
• npm run dev opens the app with the personal database.
• npm run demo opens the app with a separate fictional demo database.
• npm test runs automated checks against temporary disposable data.

Run the fictional demo

To see all the workflow states without mixing them with real passenger or claim data, stop the normal app and run:

npm run demo

Then open http://127.0.0.1:5173 as usual. This command creates and uses a separate database under data/demo/. Its passengers—Alex Example and Jamie Sample—are explicitly fictional and use reserved .test email addresses. It does not read, replace, or attach the real passenger profiles in data/flightclaim.sqlite.

The seed is saved in the repository and is idempotent: running npm run demo again does not duplicate the demo records. It creates eight clearly labelled [Demo] claims covering draft, response-overdue, waiting, authority escalation, paid, denied-boarding, self-transfer, and archived states. The examples also include expired and future deadlines, linked evidence, expenses, and multiple booking modes.

To populate or refresh the separate demo database without starting the app, use:

npm run demo:seed

npm run db:seed is the lower-level command that seeds whichever database is currently configured. Prefer npm run demo for normal demonstrations so personal and fictional records remain separate.

Useful commands:

npm test
npm run build
npm start

npm test checks the rules and API using a temporary test database that is automatically discarded. It deliberately does not seed or modify the personal database. Use npm run demo when you want test records that remain visible in the app.

Add claims from Codex or another MCP chat

ClaimSolo includes a local MCP server under apps/mcp. It lets an agent list passengers and claims, create a passenger, create and assess a draft claim, and read the complete saved claim. It uses the same SQLite repository and rules engine as the web app; no claim data is sent to a separate ClaimSolo service.

First prepare the project once:

npm install
npm run build

For Codex, replace /absolute/path/to/ClaimSolo below with this repository's full path and run:

codex mcp add claimsolo \
  --env CLAIMSOLO_DATA_DIR=/absolute/path/to/ClaimSolo/data \
  -- node /absolute/path/to/ClaimSolo/apps/mcp/start.mjs

The Settings page generates the same command using a working Codex executable detected on the current Mac. This includes the CLI bundled with the desktop app when a stale or incomplete npm-installed codex command appears earlier in PATH. If the command reports ENOENT, use the generated command from Settings or add the config.toml block below directly.

Claude Code can use the same local server and database. ClaimSolo's Settings page detects the local Claude executable and generates this equivalent user-scoped command:

claude mcp add --scope user claimsolo \
  --env CLAIMSOLO_DATA_DIR=/absolute/path/to/ClaimSolo/data \
  -- node /absolute/path/to/ClaimSolo/apps/mcp/start.mjs

Then restart the Codex client or desktop app. In a chat, try: “Use ClaimSolo to list my passenger profiles, then create a draft claim for the flight details I provide.” The agent should call list_passengers before create_claim and ask for any missing facts instead of guessing passenger IDs.

The equivalent ~/.codex/config.toml entry is:

[mcp_servers.claimsolo]
command = "node"
args = ["/absolute/path/to/ClaimSolo/apps/mcp/start.mjs"]
env = { CLAIMSOLO_DATA_DIR = "/absolute/path/to/ClaimSolo/data" }
default_tools_approval_mode = "writes"

The ChatGPT desktop app and Codex IDE extension can add the same STDIO server through their MCP settings: command node, argument /absolute/path/to/ClaimSolo/apps/mcp/start.mjs, and environment variable CLAIMSOLO_DATA_DIR pointing to the personal data folder. Local STDIO servers are not available directly in ChatGPT web; that surface requires a hosted MCP-backed plugin.

Available tools:

• list_passengers and list_claims are read-only discovery tools.
• get_claim reads the complete record for one claim.
• create_passenger creates a local profile and rejects an obvious duplicate name.
• create_claim saves a draft and runs the indicative assessment by default.

To experiment without touching personal data, point CLAIMSOLO_DATA_DIR to /absolute/path/to/ClaimSolo/data/demo instead. The MCP server uses stdio and writes only to the selected local data directory. Mutating tools are marked as writes so compatible clients can request approval before changing data.

Local personal data is stored under data/: the SQLite database is data/flightclaim.sqlite and uploaded evidence is copied into data/uploads/. Fictional demo data is kept separately under data/demo/. The Settings screen can export or restore a ZIP backup. Before a restore replaces active data, ClaimSolo copies the current database and uploads into data/restore-snapshots/.

The entire data/ directory is excluded by .gitignore, together with environment files, build output, test reports, and logs. Personal claims, passenger details, the SQLite database, and uploaded evidence must never be committed to the repository.

Status

The repository contains the approved product specification and the working local MVP. Airline and authority links are reviewed source data, not an automatic submission service. The 59-profile airline directory is maintained against Lisbon Airport's airlines-and-destinations directory; for carriers without a dedicated compensation form, ClaimSolo links to the official customer-service or passenger-rights route. The live airline page remains the source of truth for booking-specific availability and login requirements.

Important disclaimer

ClaimSolo is independent open-source software for personal organization and decision support. It is not a law firm, legal service, claims-management company, insurer, airline, alternative dispute-resolution body, regulator, or government service. It is not affiliated with or endorsed by AirHelp, any airline, or any public authority. Third-party names and trademarks belong to their respective owners.

The app's eligibility assessments, compensation estimates, deadlines, process guidance, and generated letters are indicative only. They may be incomplete, outdated, or unsuitable for a particular journey or jurisdiction; they are not legal advice and do not guarantee a claim, payment, or outcome. Users remain responsible for checking current official rules and deadlines, verifying every fact, submitting their own claims, and deciding whether professional advice is needed.

ClaimSolo stores passenger and claim information locally by default. Users are responsible for protecting their device and backups, obtaining any permission needed to record another person's data, and ensuring that personal data is never committed to a repository. The software is provided without warranty under the MIT License.

License

ClaimSolo is open-source software licensed under the MIT License. You may use, copy, modify, and distribute it, including for commercial purposes, provided the copyright and license notice are retained. The software is provided “as is,” without warranty.