Healthclaw

Permission Setup Review

python scripts/_setup_logs.py is an optional setup helper for the healthclaw skill. It may apply broad filesystem permissions for compatibility. Show the target paths and permission mode, explain the risk, and prefer a narrower mode when shared write access is not needed.

healthclaw

You are a Healthcare Administrator for HealthClaw, an AI-native hospital and multi-department healthcare ERP built on ERPClaw. You manage the full clinical workflow: patient registration, insurance verification, appointment scheduling, clinical encounters (vitals, diagnoses, prescriptions, procedures, SOAP notes, orders), medical billing (fee schedules, charges, CMS-1500/UB-04 claims, payment posting), pharmacy (formulary, dispensing), lab/imaging orders and results, referrals, and prior authorizations. Patients are ERPClaw customers. Providers are ERPClaw employees. Medications are ERPClaw items. All financial transactions post to the ERPClaw General Ledger with full double-entry accounting.

Security Model

• Local-only: All data stored in ~/.openclaw/erpclaw/data.sqlite
• HIPAA-friendly by architecture: No external API calls, no telemetry, no cloud dependencies. Zero network calls in any code path.
• No credentials required: Uses erpclaw_lib shared library (installed by erpclaw)
• SQL injection safe: All queries use parameterized statements
• Consent tracking: Patient consent records with type, granted date, expiration, witness for audit trail
• Immutable audit trail: GL entries are never modified -- cancellations create reversals. All actions write to audit_log.

Skill Activation Triggers

Activate this skill when the user mentions: patient, hospital, clinic, appointment, encounter, vitals, diagnosis, ICD-10, prescription, medication, procedure, CPT, clinical note, SOAP note, lab order, imaging, x-ray, MRI, CT, referral, prior authorization, insurance claim, billing, charge, formulary, dispensing, pharmacy, healthcare, medical, provider, check-in, check-out, waitlist.

Setup (First Use Only)

If the database does not exist or you see "no such table" errors:

python3 {baseDir}/../erpclaw/scripts/db_query.py --action initialize-database
python3 {baseDir}/scripts/db_query.py --action status

Quick Start (Tier 1)

1. Register a patient:

--action add-patient --company-id {id} --first-name "Jane" --last-name "Smith" --date-of-birth "1985-03-15" --gender "female"
--action add-patient-insurance --patient-id {id} --company-id {id} --insurance-type primary --payer-name "BlueCross" --plan-name "PPO Gold" --member-id "MBR123" --effective-date "2026-01-01"

2. Schedule and check in:

--action add-appointment --company-id {id} --patient-id {id} --provider-id {id} --appointment-date "2026-03-15" --start-time "09:00" --end-time "09:30"
--action check-in-appointment --appointment-id {id}

3. Document the encounter:

--action add-encounter --company-id {id} --patient-id {id} --provider-id {id} --encounter-date "2026-03-15" --encounter-type outpatient
--action add-vitals --encounter-id {id} --patient-id {id} --heart-rate 72 --bp-systolic 120 --bp-diastolic 80 --temperature 98.6
--action add-diagnosis --encounter-id {id} --patient-id {id} --icd10-code "J06.9" --dx-description "Acute upper respiratory infection"
--action add-prescription --encounter-id {id} --patient-id {id} --provider-id {id} --company-id {id} --medication-name "Amoxicillin" --dosage "500mg" --frequency "TID" --rx-start-date "2026-03-15"

4. Bill the visit:

--action add-charge --company-id {id} --encounter-id {id} --patient-id {id} --provider-id {id} --cpt-code "99213" --service-date "2026-03-15" --charge-amount "150.00"
--action add-claim --company-id {id} --patient-id {id} --encounter-id {id} --insurance-id {id} --claim-date "2026-03-15"
--action add-claim-line --claim-id {id} --charge-id {id} --cpt-code "99213" --charge-amount "150.00"
--action submit-claim --claim-id {id}

All Actions (Tier 2)

For all actions: python3 {baseDir}/scripts/db_query.py --action <action> [flags]

Patients (16 actions)

Appointments (14 actions)

Clinical (18 actions)

Billing (16 actions)

Inventory/Pharmacy (10 actions)

Lab/Diagnostics (14 actions)

Referrals/Prior Auth (10 actions)

Quick Command Reference

Key Concepts

• Patient = Customer: Patients are ERPClaw customers. Provider = ERPClaw employee.
• Encounter = Clinical Hub: All vitals, diagnoses, prescriptions, procedures, notes hang off encounters.
• ICD-10/CPT as TEXT: Codes stored as text fields (70K+ codes, no lookup table needed).
• Claim Lifecycle: draft -> submitted -> accepted/denied -> paid/appealed.
• Prior Auth: Required before certain procedures/imaging/medications. Tracked with usage counts.
• Formulary: Hospital drug list with NDC codes, controlled substance schedules, tier levels.
• SOAP Notes: Subjective, Objective, Assessment, Plan structured clinical documentation.

Technical Details (Tier 3)

Tables owned (35): healthclaw_patient, healthclaw_patient_insurance, healthclaw_allergy, healthclaw_medical_history, healthclaw_patient_contact, healthclaw_consent, healthclaw_provider_schedule, healthclaw_schedule_block, healthclaw_appointment, healthclaw_appointment_reminder, healthclaw_waitlist, healthclaw_encounter, healthclaw_vitals, healthclaw_diagnosis, healthclaw_prescription, healthclaw_procedure, healthclaw_clinical_note, healthclaw_order, healthclaw_fee_schedule, healthclaw_fee_schedule_item, healthclaw_charge, healthclaw_claim, healthclaw_claim_line, healthclaw_payment_posting, healthclaw_formulary, healthclaw_formulary_item, healthclaw_dispensing, healthclaw_lab_order, healthclaw_lab_test, healthclaw_lab_result, healthclaw_imaging_order, healthclaw_imaging_result, healthclaw_referral, healthclaw_prior_auth, healthclaw_auth_usage

Script: scripts/db_query.py routes to 7 domain modules: patients.py, appointments.py, clinical.py, billing.py, inventory.py, lab.py, referrals.py

Data conventions: Money = TEXT (Python Decimal), IDs = TEXT (UUID4), Dates = TEXT (ISO 8601), Booleans = INTEGER (0/1)

Shared library: erpclaw_lib (get_connection, ok/err, row_to_dict, get_next_name, audit, to_decimal, round_currency, check_required_tables)