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.
- 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
- Sub-sport categorization: Detailed sport types (trail running, indoor cycling, lap swimming, etc.)
- Pool dimensions: Pool length and unit for swimming workouts
- Coaching notes: Instructional text for each step (max 256 characters)
- Swimming equipment: Fins, kickboard, paddles, pull buoy, snorkel
- 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
- Training Stress Score (TSS): The
training_peaks_tssduration type is not yet implemented in the FIT converter. This is a TrainingPeaks-specific metric that requires additional mapping logic. Contributions welcome!
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
| Layer | Tooling |
|---|---|
| Core | TypeScript, tsup, Zod |
| CLI | yargs |
| Web App | React, Zustand, Tailwind, Radix UI |
| Testing | Vitest, Playwright |
| Package manager | pnpm |
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
Create and edit workouts visually in your browser. No installation required.
pnpm install
pnpm -r build
pnpm -r test
# Example usage
pnpm kaiord --helpFor detailed installation instructions and usage examples, see the Getting Started Guide.
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.
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.
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 testandpnpm -r build - Submit a PR: All checks must pass before merging
For detailed contribution guidelines, development workflow, and code standards, see Contributing.
- 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
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!
MIT © 2025 Pablo Albaladejo See LICENSE for details.