Kaiord — Open-Source Health & Fitness Data Framework

kaiord.com | Editor | npm

Kaiord is an open-source framework for creating, converting, and managing health & fitness data.

It provides:

@kaiord/core: a TypeScript library with format adapters for .fit, .tcx, .zwo, and .krd (Kaiord) files, plus Garmin Connect API integration.
@kaiord/cli: a command-line tool to convert, validate, and compare files across formats.
@kaiord/mcp: an MCP server exposing Kaiord tools to AI agents (Claude Desktop, Claude Code, etc.).
Workout Editor: a web application to create and edit workout files visually.

✨ Features

Visual Workout Editor - Create and edit workouts in your browser
Unified JSON-based format .krd (Kaiord Representation Definition)
Schema validation (Zod)
Round-trip safe conversions between FIT / TCX / ZWO / GCN / KRD
Hexagonal architecture & fully typed API

Supported FIT Fields

Workout Metadata

Sub-sport categorization: Detailed sport types (trail running, indoor cycling, lap swimming, etc.)
Pool dimensions: Pool length and unit for swimming workouts

Workout Steps

Coaching notes: Instructional text for each step (max 256 characters)
Swimming equipment: Fins, kickboard, paddles, pull buoy, snorkel

Duration Types

Time & distance: Standard interval durations
Calorie-based: Steps ending after burning specified calories
Power-based: Steps ending based on power thresholds (watts)
Heart rate conditionals: Steps ending based on HR thresholds (bpm)
Repeat conditionals: Repeat blocks until time/distance/calories/HR/power targets reached

Known Limitations

Training Stress Score (TSS): The training_peaks_tss duration type is not yet implemented in the FIT converter. This is a TrainingPeaks-specific metric that requires additional mapping logic. Contributions welcome!

📚 Documentation

Comprehensive documentation is available in the /docs directory:

Getting Started - Installation, basic usage, and quick examples for both library and CLI
Architecture - Hexagonal architecture, ports & adapters pattern, and design principles
Testing - Testing strategy, TDD workflow, and coverage requirements
Deployment - CI/CD pipeline, GitHub Pages deployment, and npm publishing
Contributing - Contribution guidelines, development workflow, and code standards
KRD Format - Complete specification of the Kaiord Representation Definition format
AI Agents - Guidance for AI-assisted development

🧩 Tech Stack

Layer	Tooling
Core	TypeScript, tsup, Zod
CLI	yargs
Web App	React, Zustand, Tailwind, Radix UI
Testing	Vitest, Playwright
Package manager	pnpm

🏗 Monorepo Layout

kaiord/
├─ packages/
│  ├─ core/                → domain types, schemas, ports & use cases
│  ├─ fit/                 → Garmin FIT format adapter
│  ├─ tcx/                 → Training Center XML adapter
│  ├─ zwo/                 → Zwift ZWO format adapter
│  ├─ garmin/              → Garmin Connect API adapter
│  ├─ cli/                 → command-line interface
│  ├─ mcp/                 → MCP server for AI/LLM integration
│  └─ workout-spa-editor/  → web application (https://pablo-albaladejo.github.io/kaiord)
├─ docs/   → documentation
├─ LICENSE
├─ README.md
└─ pnpm-workspace.yaml

🚀 Quick Start

Try the Web App

Launch Workout Editor →

Create and edit workouts visually in your browser. No installation required.

Use the Library

pnpm install
pnpm -r build
pnpm -r test

# Example usage
pnpm kaiord --help

For detailed installation instructions and usage examples, see the Getting Started Guide.

🚀 CI/CD Pipeline

Kaiord uses GitHub Actions for continuous integration and deployment:

Automated Testing: Multi-version testing on Node.js 22.x (Maintenance LTS) and 24.x (Active LTS)
Code Quality: ESLint, Prettier, and TypeScript strict mode validation
Release Automation: Changesets for version management and npm publishing
Security: Weekly dependency vulnerability audits, CodeQL static analysis, and automated dependency updates

For complete CI/CD documentation, deployment guides, and npm publishing instructions, see Deployment.

Mechanical invariant guards

Beyond linting, the repo enforces its architecture and conventions with 60+ purpose-built guard scripts under scripts/, each with its own co-located test suite. They run on every commit (husky pre-commit) and in CI (pnpm test:scripts), and cover, among others:

Hexagonal architecture — layer purity, adapter isolation, and the packages/core/src/ directory allowlist (check-architecture.mjs)
Package dependency graph — every @kaiord/* dependency must match the spec table (check-package-deps.mjs)
Test conventions — should -prefixed titles and Arrange/Act/Assert structure on every test (check-test-title-should.mjs, check-test-aaa.mjs)
Privacy — no runtime values interpolated into toasts or console logs (check-no-pii-leakage.mjs)
State discipline — no Zustand store writes persistence directly (check-no-zustand-writethrough.mjs)
Spec hygiene — OpenSpec format, archive dates, and auto-generated indexes stay in sync (check-spec-format.mjs, check-archive-*.mjs)

If a rule matters here, a script enforces it — documentation describes the rules, but the guards are what make them true.

Contributing

To contribute to Kaiord:

Fork and clone the repository
Create a feature branch: git checkout -b feature/my-feature
Make your changes following the code style guidelines
Add a changeset: pnpm exec changeset (for version-worthy changes)
Test locally: pnpm -r test and pnpm -r build
Submit a PR: All checks must pass before merging

For detailed contribution guidelines, development workflow, and code standards, see Contributing.

📚 References & Resources

Format Specifications

Garmin FIT SDK (JavaScript) - Official FIT protocol implementation
FIT Workout Files Cookbook - Guide to encoding workout files
FIT File Types: Workout - Workout file type specification
Training Center XML (TCX) - Garmin's XML-based format
TCX Schema (XSD) - Official Garmin TCX schema definition
Zwift Workout Format (ZWO) - Zwift's XML-based workout format

❤️ Support

If you find Kaiord useful, consider supporting its development:

⭐ Star this repo to help others discover it
💖 Sponsor on GitHub
☕ Buy me a coffee

Your support helps maintain and improve Kaiord for the fitness community!

kaiord