Pallas — athenahealth Integration Engineer for Claude Code

A Claude Code extension that embeds a senior athenahealth integration engineer in your development workflow. Proactively catches data loss bugs, teaches clinical context, guides you through safe DataView queries and API integrations, and gets smarter from every interaction through a built-in learning loop.

Try It in 30 Seconds

No install needed. Add this to any project's .claude/settings.json:

{
  "mcpServers": {
    "athena-tools": {
      "url": "https://pallas-mcp-server.azurewebsites.net/sse"
    }
  }
}

Then open Claude Code and ask: "How do I safely join PATIENT to CHART in DataView?"

This gives you all 12 MCP tools via the hosted server. For the full experience (slash commands, proactive safety rules, CLAUDE.md guidance), use the install method below.

Full Install

npx pallas-athena-tools setup

This installs to your user-level Claude Code config (~/.claude/):

• 12 MCP tools connected to the hosted knowledge base
• 9 slash commands (/sql, /athena-api, /onboard, /diagnose, etc.)
• CLAUDE.md with proactive safety rules and clinical context

Works in every project — no per-project configuration needed.

Other CLI commands

npx pallas-athena-tools status      # Check installation
npx pallas-athena-tools uninstall   # Remove everything

What It Does

• Proactive safety — Flags unsafe joins (46% data loss from PATIENTID/CHARTID mismatch), missing soft-delete filters, hardcoded credentials, and CONTEXTID issues
• Teaches the "why" — Not just "add this filter" but "here's why deleted records exist in healthcare and what happens if you include them"
• Knowledge base — 828 DataView views, 16K+ columns, 1.3K FK relationships, 1.9K API/FHIR/workflow docs
• Learning loop — Every interaction feeds lessons back to the KB. Low-risk patterns auto-merge; high-risk discoveries go through human review
• Working examples — Annotated SQL queries and API code templates in Python, TypeScript, and C#

Slash Commands

Command	Description
/onboard	Guided onboarding for new athenahealth developers
/sql <query>	Generate safe DataView SQL with CONTEXTID, soft-delete, and correct joins
/athena-api <goal>	Generate API integration code with OAuth, retry, and error handling
/diagnose <error>	Diagnose API or DataView errors with root cause explanation
/review-athena	Scan project for athenahealth anti-patterns and safety issues
/validate	Pre-deployment safety check
/explain <concept>	Deep-dive explanation of any athenahealth concept
/workflow <name>	End-to-end clinical/admin workflow guidance
/review-candidates	Review and approve/reject pending KB update candidates

MCP Tools

Tool	Description
athena_search_kb	Full-text search across the knowledge base
athena_explain_view	DataView view schema, columns, relationships, and gotchas
athena_explain_join	Safe join path between two views with identity chain warnings
athena_diagnose_error	Error diagnosis with likely causes and fixes
athena_explain_workflow	Clinical/admin workflow documentation
athena_suggest_workflow	Recommended integration approach with anti-pattern detection
athena_submit_feedback	Report learned patterns back to the KB (learning loop)
athena_list_candidates	List pending KB update candidates for review
athena_review_candidate	Approve or reject a KB update candidate
athena_report_safety_flag	Record a fired proactive safety rule (v0.2.0)
athena_report_outcome	Record artifact intent and acceptance at end of interaction (v0.2.0)
athena_command_start	Beacon for slash command usage (v0.2.0)

Learning Loop

The extension gets smarter from every developer interaction:

Developer uses Claude Code for athenahealth work
    ↓
Claude calls KB tools (search, explain, diagnose)
    → Each call is recorded (tool, duration, success/failure)
    ↓
Developer's issue is resolved
    ↓
Claude submits feedback: what worked, what was learned
    ↓
Classifier evaluates risk:
    Low risk (error patterns, gotchas) → auto-merged, confidence 0.3
    High risk (schema, identity)       → queued for human review
    ↓
Reviewer approves → promoted to KB, confidence 0.7
    ↓
Next developer benefits from this knowledge

Development

Prerequisites

• Node.js 18+
• pnpm 9+
• Claude Code

Local Development

git clone https://github.com/nous-ehr/claude_pallas_extension.git
cd claude_pallas_extension
pnpm install
pnpm build
claude    # Opens Claude Code with local MCP server

Environment Variables

Variable	Default	Description
PALLAS_KB_PATH	./data	Path to directory containing kb.json
PALLAS_LOG_LEVEL	error	Log level: error, warn, info, debug
PALLAS_TRANSPORT	stdio	Transport: stdio (local) or http (Azure)
PALLAS_PORT	8080	Port for HTTP transport
COSMOS_ENDPOINT	—	Azure Cosmos DB endpoint (enables learning loop)
COSMOS_KEY	—	Azure Cosmos DB key
COSMOS_DATABASE	pallas-kb	Cosmos DB database name

Project Structure

pallas_claude_extension/
├── CLAUDE.md                     # "Senior engineer" brain
├── data/kb.json                  # Knowledge base (828 views, 16K columns, 1.9K docs)
├── examples/                     # Annotated SQL + API code templates
├── .claude/
│   ├── settings.json             # MCP server config
│   └── commands/                 # 9 slash commands
├── packages/
│   ├── mcp-server/               # MCP server (9 tools, dual transport)
│   │   └── src/
│   │       ├── server.ts         # stdio + HTTP/SSE
│   │       ├── db/kbStore.ts     # KB with MiniSearch
│   │       ├── tools/            # 9 tool implementations
│   │       └── learning/         # Event capture, classifier, Cosmos DB
│   └── cli/                      # npm package installer
└── .github/workflows/deploy.yml  # Auto-deploy to Azure on push

Architecture

This extension is fully independent from the Athena Tools VS Code extension. They share the same knowledge base source data but have separate codebases, separate deployments, and separate evolution paths. Neither can break the other.

License

• Source code: MIT
• Knowledge base (data/kb.json): CC BY-NC-SA 4.0 — non-commercial use only; contact maintainers for commercial licensing