Practical tools for healthcare administration.
An open-source project from Open-Informatics for working through healthcare administration problems with AI. Specialist instructions, structured workflows and local calculation tools help you move from a question to a work product someone can inspect and use.
v2.0.0-beta.1 · Six focused workflows · Apache-2.0
Make healthcare intelligence usable.
A denial rate needs a denominator, a time period and a comparable group of claims. An access plan needs usable capacity and someone who can change it. A payment variance needs the right contract and a defensible expected amount.
We're building Healthcare Agents around those details. Each workflow specifies the evidence to collect, the checks to make, the decisions that need an owner and what a completed work product should contain. The goal is to make administrative work easier to investigate, explain and review.
Who it's for and how to work with it
For healthcare operators, analysts, researchers, students and developers using an agent environment. Start with a specific problem, available evidence and the person responsible for the next decision.
Read the instructions, inspect calculations and test workflow changes. That is how to contribute.
What changed in the denial cohort?
Synthetic aggregate input: 96 of 1,200 baseline claims denied; 192 of 1,200 current claims denied. The installed beta CLI calculated these values.
The rate doubled. Recoverable cash is unknown: the supplied $42,000 in denied dollars does not establish recovery.
Inspect the actual CLI result
{
"baseline_rate": 0.08,
"current_rate": 0.16,
"percentage_point_change": 8,
"relative_change": 1,
"denied_dollars": 42000,
"recoverable_dollars": null
}Actual calculation excerpt. The result download retains the input hash, evidence, human owner and completion checks.
From a rate change to a revenue cycle workup
Reconcile payer, product, service line and period. Separate first-pass and final denials; check reason codes. Test registration, authorization, coding, policy and interface hypotheses against dated evidence.
The work product: a cohort comparison, evidence gaps, hypotheses and owner-led recovery plan. Revenue cycle checks cohorts; coding/compliance and contracting review evidence. The $42,000 remains denied dollars until recovery is supported.
Help us improve it: What would you need to see before this workup was useful in a revenue cycle meeting?
Share a workflow review →Original Open-Informatics case, CC0-1.0. Replayed October 4, 2026: BuilderBob Ubuntu, Node 18.19.1. Sample provenance and licenses.
Synthetic example / Ambulatory operationsHow much capacity would reduce the backlog?
The clinic receives 120 requests a week and has 100 usable slots. Its backlog is 100 visits. The proposed change adds 40 slots a week.
- Current shortfall
- 20 slots / week
- Capacity after change
- 140 slots / week
- Capacity for backlog
- 20 slots / week
- Clearance scenario
- 5 weeks
The five-week scenario assumes stable demand and usable capacity. Operations must check staffing, visit mix, cancellations and usable slots. Keep the waitlist separate from incoming demand; clinical urgency stays with the clinical team.
The work product: a demand-and-capacity comparison, explicit assumptions and a monitored access plan. Check realized capacity, booking lead time and backlog against the scenario.
Help us improve it: Which constraints would change this calculation in your clinic?
Synthetic example / Contracting and financeWhat does the payment variance represent?
Two payment lines reference an invented contract. One has an expected payment of $1,000 and an actual payment of $800. The other has an expected payment of $500 and an actual payment of $550.
- Line 1 shortfall
- $200
- Line 2 overpayment
- $50
- Positive-only exposure
- $200
- Signed net variance
- $150
The tool retains the negative $50 offset. Check expected amounts against the executed contract, amendments, product, effective dates and remittance context. Finance validates amounts; contracting reviews the interpretation before treating a variance as collectible.
The work product: a line-level variance register linked to contract references, unresolved assumptions and an accountable disposition. A dispute draft can then be prepared for review where appropriate.
Help us improve it: Which adjustments or contract provisions should a reviewer check before escalating the variance?
Which task fits your job?
Open a task to see its artifact, calculation and sample. All six samples use synthetic data. Select an explicit workflow ID; free-text routing offers discovery candidates.
Denial spikeRevenue cycle
Compare denial cohorts and assign evidence pulls. This demo returns 8% → 16%, +8 percentage points; recoverable cash stays unknown.
denial-spike-workup
Access backlogAmbulatory operations
Build a monitored access plan. The sample is 20 slots short each week; added usable capacity gives a five-week backlog scenario.
ambulatory-access-backlog
Survey evidenceQuality and compliance
Build an owner-led standard-to-evidence gap register. The sample retains two findings and one missing evidence item; presence does not certify compliance.
survey-readiness-gap-review
Appeal evidenceAuthorization team
Prepare an administrative appeal packet. The sample compares supplied dates (30 calendar days) and identifies a missing clinician statement.
prior-authorization-appeal-workup
Underpayment reviewContracting and finance
Prepare a contract-linked variance register. The sample retains a $200 shortfall and $50 overpayment: $150 signed net.
payer-contract-underpayment-review
Discharge barriersCare operations
Assign owners and dependencies for aggregate barriers. The sample sums six category cases and 13 reported avoidable days; readiness remains a human decision.
discharge-barrier-workplan
The five other samples are unchanged Apache-2.0 release fixtures at 72fe0a6. The library retains 51 specialists in 10 domains and 16 legacy workups.
Replay the beta with sample data.
Use an empty folder, Node.js 18.14.1+, npm and curl. Bash checked on BuilderBob Ubuntu, Node 18.19.1. No model account is needed for this local calculation.
Choose the beta explicitly. npm next is 2.0.0-beta.1; latest remains 1.5.0. The command below pins the beta instead of relying on a moving tag.
Looking for the stable library instead?
Stable 1.5.0 does not provide this beta replay. In a separate empty project, use npm install --ignore-scripts --save-exact healthcare-agents@1.5.0. Read the stable-version instructions.
mkdir healthcare-agents-demo
cd healthcare-agents-demo
npm init -y
npm install --ignore-scripts --save-exact healthcare-agents@2.0.0-beta.1
curl --fail --location --output denial-spike-workup.json https://open-informatics.org/assets/healthcare-agents/denial-spike-workup.json
npx --no-install healthcare-agents admin run denial-spike-workup.jsonSuccess check: look for draft_for_human_review, "baseline_rate": 0.08, "current_rate": 0.16, "percentage_point_change": 8 and "recoverable_dollars": null. The JSON also records the input hash, evidence and human owner.
Try another workflow or recover from an error
Save another task sample in the demo folder, then use npx --no-install healthcare-agents admin run sample.json. Retain its workflow ID and evidence.
If a download fails, save its linked JSON manually. curl --fail rejects HTTP error pages. Check npm ls healthcare-agents, correct the filename and retry. Missing evidence or conflicting input should return a typed error; retain validation.
The CLI prints a review draft. A qualified host/model develops the fuller artifact; follow the pinned host guide.
A fresh npm install matched all 599 packaged files to reviewed source. Synthetic checks verify installation and local contracts; model quality and customer benefit remain unvalidated.
Codex CLI 0.160.0 POSIX profiles have bounded BuilderBob qualification. Claude/Azure/Databricks live acceptance is pending. ChatGPT web needs an approved authenticated service. Qualify other hosts separately.
Use synthetic or approved aggregate evidence in a permitted environment. This is not a PHI-processing environment. Qualified humans retain consequential judgment.
Instructions, evidence, calculations and review.
We separate model-assisted work from repeatable calculations. Skills and specialist references supply context; workflow contracts define evidence, checks, owners and completion criteria. The host develops the analysis, questions and draft work product.
- Choose the task. Select an explicit workflow and the relevant specialist.
- Declare the evidence. Supply a human owner and dated evidence for each input field.
- Check and calculate. Local tools validate the case and calculate supported quantities.
- Develop and review. The host model drafts the fuller artifact; qualified owners verify sources and authorize consequential actions.
Inspect the tools, builder and evaluation
Tools reject missing fields, impossible denominators and invalid dates. Results retain evidence, owner and input hash; attribution does not authenticate sources.
Eight read-only MCP tools expose discovery, six calculations and an in-memory custom draft. The CLI runs directly. Hosts supply models and permissions; the package makes no model calls.
The builder takes an outcome, specialist, owner, evidence fields and acceptance criteria; it produces a skill, reference, case template and hash manifest. Test synthetic and incomplete cases. Custom templates have no built-in calculator.
One bounded Codex session ran 12 synthetic tasks with actual MCP calls on a prepared snapshot; implementation-owner checks passed. Repeated practitioner acceptance and customer-host testing remain future work.
Help us make this useful.
Tell us what you tried, what was missing or what you would work on. A specific task, incorrect result or better example gives us something to act on. You do not need to contribute code.
This prepares a public GitHub issue draft. Review it on GitHub, sign in if needed, then publish it yourself. This site does not receive or store your entry. Replies stay in the issue thread; no email address is needed.
Use synthetic examples and public links. Do not include patient information, credentials, private contract terms or confidential organizational data.
Use the questions that fit your task. These are writing prompts; they do not prefill or record a purpose.
Title: 8–120 characters. Description: 40–1,800. Link public synthetic examples for longer details.
I tried a workflow
Describe the task, expected result and what happened. A synthetic reproduction helps us investigate.
- Workflow ID, package version, Node version and host/model, if known
- What you expected and what happened instead
- Steps to reproduce, typed error, or a public synthetic example
- Optional: time to first successful replay and whether you would use it again
I have a workflow idea
Start with the work product you need, rather than a feature list.
- The task you are trying to complete
- What the final work product should contain
- Evidence sources normally available—describe them without sharing the data
- Who would review or use the result
I want to contribute
You do not need to contribute code. Propose a small piece of work we can review together.
- Area: healthcare domain review, synthetic examples, research, engineering, documentation or teaching
- A workflow or question you would like to work on
- How to start: review an example, improve a workflow, test an integration or discuss research
- Optional: your role and relevant public work or profile
I have a question
Tell us what you are trying to understand and where the instructions leave a gap.
- The task or decision behind your question
- The workflow or documentation you looked at
- What would help you take the next step
Prefer email? Open email draft ↗, complete the prompts and send it in your mail app. If no app opens, write to clyons@ajhcs.org. Text entered below is not copied into the email draft.
Your browser checks the required fields before opening GitHub. An issue is received only after you publish it there. If sign-in interrupts the draft, return here; you can also paste your text into a blank GitHub issue.
Build it around work people can evaluate.
We want practitioners to make the workflows more representative of actual healthcare administration: better examples, harder cases, clearer review criteria and evidence about where an agent helps or creates more work.
Where we want to take it
Researchers can test reliability across tasks, models and environments. Developers can improve installation, tools, evidence handling and custom workflows. Operators and educators can assess work products against their standards for colleagues or students.
Healthcare Data MCP handles public healthcare evidence. An optional importer maps receipts into supported cases, preserving sources. Further integration needs verified field mappings and coverage. Inspect the importer and its limits.
Bring a concrete problem, test a question or improve a workflow.
Follow releases and reproducible fixes. Keep the version with each result and replay your synthetic case after an upgrade.
Future case studies need reviewed evidence, documented results and limits, and participant permission. These are synthetic worked examples.