Claero

Claero is a desktop medical billing advocate that reads bills and insurance docs, checks what you actually owe, flags likely errors, and tells you what to pay, dispute, or ignore.

Comment

Project Story

Inspiration

Healthcare in the United States is expensive in a way that feels structurally unfair, and I felt that immediately after moving from Spain to the US.

In Spain, healthcare felt much more predictable from the patient side. In the US, even when you have insurance, you are still expected to understand bills, EOBs, denials, prior authorizations, deductible math, provider billing language, and plan rules that are usually buried in PDFs nobody reads until something goes wrong. The hardest part is not just the cost itself. It is that the patient is the least equipped person in the system, while insurers and provider billing offices have more information, more process, and better tools.

That imbalance is what inspired Claero.

I wanted to build something that acts like a personal medical billing advocate. Not another claims portal, not another dashboard full of raw codes, and not a generic chatbot. Something that reads the bill, checks the plan, explains what matters, and tells the user what to pay, what to dispute, and what to ignore.

The first real test made the idea feel real very quickly. On the first bill I tried it with, I realized I would have saved $80. That is not a dramatic headline number by itself, but that is exactly why this problem matters. People lose money in small, repeated, easy-to-miss ways all the time. Those amounts are often just low enough that people give up and pay them. But over time, they add up.

What it does

Claero is a desktop medical billing intelligence and advocacy app built for patients navigating the US healthcare system. It is designed to run quietly in the background, detect relevant health-related activity, ingest documents like medical bills and insurance paperwork, analyze what happened, and surface only the information that actually matters.

At a product level, Claero does four things:

  1. It watches for relevant signals, such as health-related emails, uploaded documents, and care events.
  2. It extracts and organizes billing and insurance information into a usable context.
  3. It compares what the patient is being charged against what likely should have happened under their coverage.
  4. It explains the result in plain language and recommends the next step.

The most important design principle is that the user should not have to reconstruct the case from scratch every time. The app is supposed to feel like an advocate that has already done the boring work before you even open it.

How I built it

Claero is built as a desktop-first, local-first application. The current implementation uses an Electron shell with a React + TypeScript frontend and Tailwind CSS for the interface. The desktop process acts as the orchestration layer for the product: it handles notifications, integrations, background monitoring, tool execution, and AI routing.

The reasoning layer supports multiple modes:

  • OpenAI for strong hosted reasoning and orchestration
  • Perplexity Sonar for grounded checking and research-heavy workflows
  • Ollama for local inference and privacy-first setups

That flexibility was important because I did not want the product to depend entirely on a single model path. Some users will prefer the strongest hosted reasoning possible, while others will care much more about keeping sensitive documents local and running the system on their own hardware.

A big technical lesson from this project was that the model is not really the product. The product is the evidence pipeline around the model.

When the user asks a question, the assistant is not answering from a blank prompt. Claero builds context from several sources:

  • the active care episode
  • linked documents
  • previous conversation history
  • the current workspace state
  • insurance carrier information
  • uploaded plan files
  • relevant email evidence
  • relevant calendar events

That context then flows into the orchestration layer, where the agent can call tools to retrieve more evidence before answering.

Tool-driven reasoning

One of the most important implementation decisions was to make the assistant tool-driven instead of just prompt-driven.

The agent can call tools to:

  • search the user’s health-related emails through Gmail API or IMAP
  • fetch recent and upcoming appointments from calendar integrations
  • find, create, or update care episodes
  • inspect plan documents already linked to the case
  • look up CPT / HCPCS codes
  • predict likely billing codes and costs for upcoming procedures
  • record potential savings when it finds an overcharge or discrepancy
  • run web-backed research when it needs fresh external references

That matters because medical billing is not a domain where “smart sounding” AI is enough. The assistant needs evidence. It needs to search the user’s own context, compare it to plan rules, and use current references when needed.

Search and evidence gathering

Claero uses multiple search layers depending on the question.

If the user is asking something patient-specific, the system searches local context:

  • episodes
  • documents
  • prior conversation
  • email evidence
  • calendar activity

If the user is asking something coverage-specific, the system checks plan documents already linked to the case.

If the user is asking about a procedure, expected cost, or billing code, the agent can run grounded research to look up likely CPT/HCPCS code families, cost ranges, and common billing risks.

This was one of the biggest things I learned while building the project: the hard part is not getting a model to generate language. The hard part is deciding what evidence is relevant, where to fetch it from, and what the model is actually justified in concluding.

Plan document handling

A major trust challenge in this space is that insurance rules are usually buried inside long PDFs. Instead of relying only on summaries, Claero is designed to work directly with uploaded plan files like SBCs, coverage handbooks, and similar documents.

In the current architecture, relevant plan PDFs can be converted into image-based inputs and attached directly into the model context so the assistant can reason from the actual pages instead of from a lossy short summary. That helps the system answer questions like:

  • Is durable medical equipment covered?
  • Is prior authorization required?
  • Should this be a copay or coinsurance situation?
  • Has the patient likely already met the deductible?

That source-level grounding matters because if the app tells someone a charge might be wrong, it needs to be easy to understand why.

Email and calendar integration

Another important piece of the build was reducing user effort. Most people are not going to manually organize their medical billing life into a clean dataset before they ask for help. So the app is designed to proactively gather signals.

Through Gmail API or IMAP, Claero can search for:

  • EOBs
  • denial letters
  • prior auth notices
  • provider billing emails
  • estimates and follow-up correspondence

Through calendar access, it can also pull recent or upcoming care events and use that information to connect later billing activity back to a real encounter.

That means the system can start to piece together sequences like:

  • appointment happened
  • bill arrived
  • EOB arrived
  • denial letter followed
  • issue now needs action

This is what makes the product feel more like an advocate and less like a form the user has to fill out.

Notifications and ambient behavior

Claero is designed to run silently on the user’s own machine. That was a deliberate product and technical choice.

I did not want it to be a tool you have to remember to open. I wanted it to behave more like background infrastructure for the patient. It can sit quietly on your hardware, process information locally, and notify you only when there is something actionable or reassuring.

That includes cases like:

  • a new bill arrived
  • a denial was detected
  • a likely discrepancy was found
  • a prior authorization issue might matter for an upcoming appointment
  • enough context has been assembled to review a case

That notification layer was harder than it looks. It is easy to make software noisy. It is hard to make it genuinely helpful.

iMessage with Photon

One of the most interesting parts of the build is the iMessage experience using Photon.

I wanted Claero to feel less like a dashboard you occasionally open and more like a person you can reach out to when something stressful lands in your inbox. Messaging is a much more natural interface for that than a traditional claims portal.

So the system is designed so that incoming iMessage threads can be routed into the same context-aware agent layer. The assistant can keep lightweight conversation state, detect which medical episode the user is referring to, use the same evidence and search tools, and respond in short, natural message bubbles.

That changes the emotional quality of the product. Instead of “let me log in and decode this billing event,” the experience becomes “let me text the thing that already knows what is going on.”

That was a major lesson for me: in healthcare, trust is not only about accuracy. It is also about presence.

Self-hosting and privacy-first design

Healthcare data is incredibly sensitive, so I cared a lot about keeping the system close to the user. Claero is designed so that it can be self-hosted and run on the user’s own hardware, with local inference available through Ollama and with a local-first workflow for files and background monitoring.

That means the product does not have to be a traditional SaaS where everything is uploaded into a centralized cloud backend just to understand a bill. If the user wants the software to live on their own machine and keep as much as possible local, that path exists.

That local-first architecture is not just a technical preference. It is part of the product philosophy. If the app is supposed to be on the patient’s side, it should also respect ownership and privacy.

Challenges I ran into

The hardest challenge was not building chat. It was building trustworthy orchestration.

A system like this has to know:

  • when to search local context
  • when to inspect plan documents
  • when to use web-backed research
  • when there is enough evidence to make a recommendation
  • when uncertainty needs to be explicit
  • when to notify the user and when to stay quiet

That forced me to think much more like a systems designer than just a prompt engineer.

The second major challenge was balancing privacy and capability. Healthcare is a domain where local-first design really matters, but the strongest reasoning capabilities are often in hosted models. Supporting both hosted and local modes while keeping the product behavior coherent was a major architecture challenge.

Another challenge was that medical billing is messy by nature. A useful product cannot pretend everything is deterministic. It needs to separate:

  • confirmed issues
  • likely issues
  • missing-context situations
  • things the patient can ignore
  • things that need action now

Designing those boundaries clearly was essential.

And finally, there was a human challenge: this is a stressful problem space. The app cannot just be technically clever. It has to reduce anxiety, not increase it.

What I learned

The biggest lesson from building Claero is that the model is not the product. The real product is everything around the model:

  • context assembly
  • document ingestion
  • plan grounding
  • evidence retrieval
  • tool calling
  • notification discipline
  • action-oriented outputs

That is what turns an LLM into something that can actually help a patient save money.

I also learned how much product design matters in serious domains. The interface and tone cannot feel like a generic AI assistant or an enterprise portal. It has to feel calm, direct, and protective of the user’s attention.

And I learned that small savings matter. The first real test found a case where I would have saved $80. That single number was enough to validate the project for me, because it shows the shape of the problem: people are losing money in small, repeated ways that are easy to miss and hard to contest. If software can consistently catch those moments, it can return real money and real peace of mind.

What’s next

The next step for Claero is continuing to deepen the advocacy layer:

  • stronger end-to-end bill review
  • better appeal and dispute drafting
  • richer linking between appointments, claims, bills, and emails
  • more seamless messaging workflows
  • stronger local-first deployment for privacy-conscious users

The long-term vision is simple: patients should not be alone when the billing system gets something wrong. Claero is my attempt to build the software advocate I wish existed the moment I started dealing with US healthcare myself.

Built With

Share this project:

Updates