Skip to content

dochobbs/clinicalcli

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
docs
docs
 
 
prompts
prompts
 
 
src
src
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
clinical
clinical
 
 
clinical-shell
clinical-shell
 
 
setup.sh
setup.sh
 
 

Repository files navigation

Clinical CLI - Pediatric Clinical Decision Support Tool

Fast, interactive AI-powered clinical decision support for pediatric care.

Version Python License

🚀 Quick Start

# Clone and setup
git clone https://github.com/dochobbs/clinicalcli.git
cd clinicalcli
./setup.sh

# Start interactive shell
./clinical-shell

# Try it out!
⚕️  clinical> d amoxicillin --weight 52# --age 5yo
⚕️  clinical> cds 5yo with fever x3 days, ear pain
⚕️  clinical> help

That's it! Responses stream in real-time. ⚡

✨ Key Features

🎯 Interactive Shell Mode

  • Real-time streaming responses - See results immediately (200-500ms)
  • Single-line commands - Fast, natural workflow
  • Tab completion - Quick command entry
  • Command history - Arrow keys to recall
  • Copy on demand - copy command when you need it

💊 Clinical Commands

  • drug / d - Drug lookup with weight-based dosing
  • dose - Quick dose calculation
  • compare - Compare multiple medications
  • cds / c - Clinical decision support with red flag detection
  • ddx - Differential diagnosis generation
  • note - Clinical notes (SOAP, progress, consult, discharge)
  • parse - Analyze PDF/image documents

🤖 AI Model Support

  • Default: Claude Haiku 4.5 (1-2 sec, optimized for speed) ⚡
  • Quality: Claude Sonnet 4.5 (2-5 sec, best for complex cases)
  • Offline: LM Studio and Ollama for local models
  • Easy switching: model llama3.2 or model claude-sonnet-4-5-20250929

🛡️ Safety Features

  • 3-layer dosing validation - Weight, age, and range checking
  • Red flag detection - Emergent condition identification
  • Anti-hallucination prompts - Source citation requirements
  • Session isolation - No cross-patient data retention

📖 Documentation

Start here: docs/README.md

Quick Links

See full documentation in docs/ directory.

💡 Usage Examples

Drug Lookup with Dosing

⚕️  clinical> d amoxicillin --weight 52# --age 5yo

Response:

# Amoxicillin - Pediatric Dosing
**Patient:** 52 lbs (23.6 kg), 5 years old

## Standard Dosing for Acute Otitis Media
- Dose: 80-90 mg/kg/day divided BID
- Calculation: 23.6 kg × 45 mg/kg = 1062 mg/day
- Give: 530 mg BID (use 400 mg/5 mL suspension)
- Volume: 6.5 mL BID

[Full response continues streaming...]

Tip: Use 'copy' command to copy this to clipboard

Clinical Decision Support

⚕️  clinical> cds 5yo with fever x3 days, ear pain, decreased hearing

Response:

# Clinical Assessment: Acute Otitis Media (AOM)

## Key Features
This 5-year-old with fever, ear pain, and decreased hearing...
[Comprehensive assessment streams in real-time]

⚕️  clinical> copy
✓ Copied 2103 characters to clipboard

Quick Dose Calculation

⚕️  clinical> dose ibuprofen 40#

Response:
# Ibuprofen - Quick Dose
- Weight: 40 lbs (18.2 kg)
- Dose: 10 mg/kg = 182 mg
- Give: 9 mL of 100 mg/5 mL suspension
- Frequency: Every 6-8 hours PRN

Switch Models

⚕️  clinical> model
═══ Available Models ═══

Anthropic Claude (Cloud):
  [✓] claude-haiku-4-5-20251001    # Default, fast
  [ ] claude-sonnet-4-5-20250929   # Best quality

⚕️  clinical> model claude-sonnet-4-5-20250929
✓ Switched to Anthropic model: claude-sonnet-4-5-20250929

🎨 Why This Tool?

Speed

  • ⚡ Streaming responses - Start reading in 200ms
  • ⚡ Claude Haiku 4.5 default - 1-2 second responses
  • ⚡ Single-line commands - No Ctrl+D needed

User Experience

  • ✅ No interruptions - Copy only when you want
  • ✅ Natural workflow - Like talking to a colleague
  • ✅ Rich formatting - Clear, readable output
  • ✅ Tab completion - Fast command entry

Clinical Focus

  • 🎯 Pediatric-optimized - Weight-based dosing, age-appropriate guidance
  • 🎯 Safety-first - Multiple validation layers
  • 🎯 Red flag detection - Critical condition alerts
  • 🎯 Evidence-based - Source citation requirements

📋 Requirements

  • Python: 3.9 or higher
  • API Key: Anthropic API key (set in ~/.zshrc as ANTHROPIC_API_KEY)
  • Optional: LM Studio or Ollama for offline local models
  • Platforms: macOS, Linux, Windows

🔧 Installation

Automated Setup (Recommended)

git clone https://github.com/dochobbs/clinicalcli.git
cd clinicalcli
./setup.sh

Manual Setup

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Set API key (if not already in ~/.zshrc)
export ANTHROPIC_API_KEY="your-api-key-here"

Verify Installation

./clinical-shell
⚕️  clinical> help

🎯 Common Workflows

Quick Drug Lookup

./clinical-shell
⚕️  clinical> dose amox 52#
⚕️  clinical> q

Time: ~10 seconds

Complete Patient Assessment

./clinical-shell
⚕️  clinical> d amoxicillin --weight 52# --age 5yo
⚕️  clinical> cds 5yo with fever x3 days, ear pain, decreased hearing
⚕️  clinical> note 5yo with AOM, starting amoxicillin
⚕️  clinical> copy
⚕️  clinical> q

Time: ~2 minutes

All-Day Clinic Session

./clinical-shell
# Leave running all day
⚕️  clinical> d amox --weight 52#      # Patient 1
⚕️  clinical> d cefdinir --weight 30#  # Patient 2
⚕️  clinical> cds 12yo with headache...
⚕️  clinical> stats                     # Check session stats
⚕️  clinical> q

🚨 HIPAA Compliance

⚠️ Protected Health Information (PHI) Warning

  • ✅ BAA Required - Use only with Anthropic API under signed Business Associate Agreement
  • ✅ Authorized Use - Ensure proper authorization for PHI processing
  • ✅ Secure Handling - Do not share outputs containing PHI insecurely
  • ✅ Audit Trail - Session logs available via stats command
  • ✅ Session Isolation - No data persists between sessions

This tool is designed for HIPAA-compliant use under Anthropic's BAA.

📊 Performance

Response Times

Model Speed Quality Use Case
Claude Haiku 4.5 (default) 1-2 sec ⚡⚡⚡ Excellent Quick lookups, routine queries
Claude Sonnet 4.5 2-5 sec ⚡⚡ Outstanding Complex cases, critical decisions
Local Models (offline) 30-60 sec ⚠️ Good Emergency offline reference

Streaming: First words appear in ~200-500ms regardless of model!

🔄 Model Management

Available Models

Cloud (Anthropic) - Recommended:

  • claude-haiku-4-5-20251001 - Default, optimized for speed
  • claude-sonnet-4-5-20250929 - Best quality for complex cases

Local (Offline):

  • LM Studio - User-friendly GUI, any GGUF model
  • Ollama - CLI-based, scriptable

Switching Models

⚕️  clinical> model                            # List available
⚕️  clinical> model claude-sonnet-4-5-20250929 # Switch to Sonnet
⚕️  clinical> model llama3.2                   # Switch to Ollama (if running)

See Model Selection Guide for details.

🛠️ Development

Project Structure

clinicalcli/
├── src/
│   ├── cli.py              # Single-command CLI
│   ├── interactive.py      # Interactive shell (main)
│   ├── model_manager.py    # Multi-model support
│   ├── utils.py            # Shared utilities
│   ├── dose_validator.py   # Safety validation
│   └── commands/           # Command modules
├── prompts/                # System prompts
├── docs/                   # Documentation
├── requirements.txt        # Dependencies
└── clinical-shell          # Interactive launcher

Adding Features

See Development Guide (coming soon)

🐛 Troubleshooting

API Key Issues

# Check if set
echo $ANTHROPIC_API_KEY

# If empty, add to ~/.zshrc
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

Import Errors

# Ensure virtual environment is activated
source .venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Slow Performance

  • Use Haiku (default) - 2-3x faster than Sonnet
  • Local models are slow - See Performance Guide
  • Check internet connection - Cloud models require connectivity

Command Not Found

# Make shell executable
chmod +x clinical-shell

# Or run directly
python -m src.interactive

🗺️ Roadmap

Current Version: 1.3.0

  • ✅ Interactive shell mode
  • ✅ Streaming responses
  • ✅ Multi-model support (Claude, LM Studio, Ollama)
  • ✅ Copy on demand
  • ✅ Comprehensive documentation

Planned Features

  • Response caching for offline access
  • Custom prompt templates
  • Batch processing mode
  • Integration with EHR systems
  • Extended local model optimization
  • Multi-language support

See ROADMAP.md for detailed plans (coming soon).

📝 License

Internal Use Only - Requires valid Anthropic API credentials and Business Associate Agreement for PHI processing.

🙏 Acknowledgments

  • Anthropic - Claude AI models and HIPAA-compliant API
  • Rich - Beautiful terminal formatting
  • Prompt Toolkit - Interactive shell features

📞 Support

Documentation

Issues

Report issues at: https://github.com/dochobbs/clinicalcli/issues

Version: 1.3.0 Last Updated: November 9, 2025 Default Model: Claude Haiku 4.5 (fast!) Status: Production Ready ✅

⭐ Quick Command Reference

# Interactive Shell
./clinical-shell           # Start shell

# Drug Commands
d <drug> --weight <wt>     # Drug lookup with dosing
dose <drug> <weight>       # Quick dose
compare <d1> <d2>          # Compare drugs

# Clinical Commands
cds <presentation>         # Clinical decision support
ddx <presentation>         # Differential diagnosis
note <info>                # Generate note
parse <file>               # Analyze document

# Utilities
copy                       # Copy last output
model                      # List/switch models
stats                      # Session statistics
help                       # Show help
quit                       # Exit

# Examples
d amoxicillin --weight 52# --age 5yo
cds 5yo with fever, ear pain
note 5yo with AOM, starting antibiotics
copy

Get started in 5 minutes: Quick Start Guide

About

cli CDS tool use with claude or local models

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages