https://github.com/pablo-albaladejo/kaiord
Open-source TypeScript framework for converting between FIT, TCX, ZWO, and Garmin Connect fitness data formats. By Pablo Albaladejo.
https://github.com/pablo-albaladejo/kaiord
ai-assisted fit-files fitness fitness-data garmin health open-source typescript workout zwift
Last synced: about 1 month ago
JSON representation
Open-source TypeScript framework for converting between FIT, TCX, ZWO, and Garmin Connect fitness data formats. By Pablo Albaladejo.
- Host: GitHub
- URL: https://github.com/pablo-albaladejo/kaiord
- Owner: pablo-albaladejo
- License: mit
- Created: 2025-11-11T13:37:10.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-05-18T13:36:10.000Z (about 2 months ago)
- Last Synced: 2026-05-18T13:39:02.377Z (about 2 months ago)
- Topics: ai-assisted, fit-files, fitness, fitness-data, garmin, health, open-source, typescript, workout, zwift
- Language: TypeScript
- Homepage: https://kaiord.com
- Size: 10.8 MB
- Stars: 7
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Roadmap: docs/roadmap-fit-implementation.md
- Notice: NOTICE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Kaiord — Open-Source Health & Fitness Data Framework
**[kaiord.com](https://kaiord.com)** | [Editor](https://kaiord.com/editor/) | [npm](https://www.npmjs.com/org/kaiord)
[](./LICENSE)
[](https://www.typescriptlang.org/)
[](https://github.com/pablo-albaladejo/kaiord/actions/workflows/ci.yml)
[](https://codecov.io/gh/pablo-albaladejo/kaiord)
[](https://www.npmjs.com/package/@kaiord/core)
[](https://www.npmjs.com/package/@kaiord/cli)
[](https://github.com/sponsors/pablo-albaladejo)
**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](https://pablo-albaladejo.github.io/kaiord)**: a web application to create and edit workout files visually.
---
## ✨ Features
- **[Visual Workout Editor](https://pablo-albaladejo.github.io/kaiord)** - 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](./docs/getting-started.md)** - Installation, basic usage, and quick examples for both library and CLI
- **[Architecture](./docs/architecture.md)** - Hexagonal architecture, ports & adapters pattern, and design principles
- **[Testing](./docs/testing.md)** - Testing strategy, TDD workflow, and coverage requirements
- **[Deployment](./docs/deployment.md)** - CI/CD pipeline, GitHub Pages deployment, and npm publishing
- **[Contributing](./CONTRIBUTING.md)** - Contribution guidelines, development workflow, and code standards
- **[KRD Format](./docs/krd-format.md)** - Complete specification of the Kaiord Representation Definition format
- **[AI Agents](./AGENTS.md)** - 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 →](https://pablo-albaladejo.github.io/kaiord)**
Create and edit workouts visually in your browser. No installation required.
### Use the Library
```bash
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](./docs/getting-started.md)**.
---
## 🚀 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
For complete CI/CD documentation, deployment guides, and npm publishing instructions, see **[Deployment](./docs/deployment.md)**.
### Contributing
To contribute to Kaiord:
1. **Fork and clone** the repository
2. **Create a feature branch**: `git checkout -b feature/my-feature`
3. **Make your changes** following the code style guidelines
4. **Add a changeset**: `pnpm exec changeset` (for version-worthy changes)
5. **Test locally**: `pnpm -r test` and `pnpm -r build`
6. **Submit a PR**: All checks must pass before merging
For detailed contribution guidelines, development workflow, and code standards, see **[Contributing](./CONTRIBUTING.md)**.
---
## 📚 References & Resources
### Format Specifications
- [Garmin FIT SDK (JavaScript)](https://github.com/garmin/fit-javascript-sdk) - Official FIT protocol implementation
- [FIT Workout Files Cookbook](https://developer.garmin.com/fit/cookbook/encoding-workout-files/) - Guide to encoding workout files
- [FIT File Types: Workout](https://developer.garmin.com/fit/file-types/workout/) - Workout file type specification
- [Training Center XML (TCX)](https://en.wikipedia.org/wiki/Training_Center_XML) - Garmin's XML-based format
- [TCX Schema (XSD)](https://www8.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd) - Official Garmin TCX schema definition
- [Zwift Workout Format (ZWO)](https://zwift.com) - 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](https://github.com/sponsors/pablo-albaladejo)**
- ☕ **[Buy me a coffee](https://buymeacoffee.com/pabloalbaladejo)**
Your support helps maintain and improve Kaiord for the fitness community!
---
## 📜 License
MIT © 2025 Pablo Albaladejo
See [LICENSE](./LICENSE) for details.