{"id":44130788,"url":"https://github.com/pablo-albaladejo/kaiord","last_synced_at":"2026-05-24T10:00:46.680Z","repository":{"id":323711792,"uuid":"1094267295","full_name":"pablo-albaladejo/kaiord","owner":"pablo-albaladejo","description":"Open-source TypeScript framework for converting between FIT, TCX, ZWO, and Garmin Connect fitness data formats. By Pablo Albaladejo.","archived":false,"fork":false,"pushed_at":"2026-05-18T13:36:10.000Z","size":11273,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T13:39:02.377Z","etag":null,"topics":["ai-assisted","fit-files","fitness","fitness-data","garmin","health","open-source","typescript","workout","zwift"],"latest_commit_sha":null,"homepage":"https://kaiord.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pablo-albaladejo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"docs/roadmap-fit-implementation.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"pablo-albaladejo","custom":["https://buymeacoffee.com/pabloalbaladejo"]}},"created_at":"2025-11-11T13:37:10.000Z","updated_at":"2026-05-18T13:33:30.000Z","dependencies_parsed_at":"2026-02-12T05:09:52.503Z","dependency_job_id":null,"html_url":"https://github.com/pablo-albaladejo/kaiord","commit_stats":null,"previous_names":["pablo-albaladejo/kaiord"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/pablo-albaladejo/kaiord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablo-albaladejo%2Fkaiord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablo-albaladejo%2Fkaiord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablo-albaladejo%2Fkaiord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablo-albaladejo%2Fkaiord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pablo-albaladejo","download_url":"https://codeload.github.com/pablo-albaladejo/kaiord/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablo-albaladejo%2Fkaiord/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33429192,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assisted","fit-files","fitness","fitness-data","garmin","health","open-source","typescript","workout","zwift"],"created_at":"2026-02-08T22:10:16.672Z","updated_at":"2026-05-24T10:00:46.675Z","avatar_url":"https://github.com/pablo-albaladejo.png","language":"TypeScript","funding_links":["https://github.com/sponsors/pablo-albaladejo","https://buymeacoffee.com/pabloalbaladejo"],"categories":[],"sub_categories":[],"readme":"# Kaiord — Open-Source Health \u0026 Fitness Data Framework\n\n**[kaiord.com](https://kaiord.com)** | [Editor](https://kaiord.com/editor/) | [npm](https://www.npmjs.com/org/kaiord)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)\n\n[![CI](https://github.com/pablo-albaladejo/kaiord/actions/workflows/ci.yml/badge.svg)](https://github.com/pablo-albaladejo/kaiord/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/pablo-albaladejo/kaiord/branch/main/graph/badge.svg)](https://codecov.io/gh/pablo-albaladejo/kaiord)\n[![npm version](https://badge.fury.io/js/@kaiord%2Fcore.svg)](https://www.npmjs.com/package/@kaiord/core)\n[![npm version](https://badge.fury.io/js/@kaiord%2Fcli.svg)](https://www.npmjs.com/package/@kaiord/cli)\n[![Sponsor](https://img.shields.io/badge/Sponsor-❤️-pink?logo=github-sponsors)](https://github.com/sponsors/pablo-albaladejo)\n\n**Kaiord** is an open-source framework for creating, converting, and managing health \u0026 fitness data.\n\nIt provides:\n\n- `@kaiord/core`: a TypeScript library with format adapters for **.fit**, **.tcx**, **.zwo**, and **.krd** (Kaiord) files, plus Garmin Connect API integration.\n- `@kaiord/cli`: a command-line tool to convert, validate, and compare files across formats.\n- `@kaiord/mcp`: an MCP server exposing Kaiord tools to AI agents (Claude Desktop, Claude Code, etc.).\n- **[Workout Editor](https://pablo-albaladejo.github.io/kaiord)**: a web application to create and edit workout files visually.\n\n---\n\n## ✨ Features\n\n- **[Visual Workout Editor](https://pablo-albaladejo.github.io/kaiord)** - Create and edit workouts in your browser\n- Unified JSON-based format `.krd` (Kaiord Representation Definition)\n- Schema validation (Zod)\n- Round-trip safe conversions between FIT / TCX / ZWO / GCN / KRD\n- Hexagonal architecture \u0026 fully typed API\n\n### Supported FIT Fields\n\n#### Workout Metadata\n\n- **Sub-sport categorization**: Detailed sport types (trail running, indoor cycling, lap swimming, etc.)\n- **Pool dimensions**: Pool length and unit for swimming workouts\n\n#### Workout Steps\n\n- **Coaching notes**: Instructional text for each step (max 256 characters)\n- **Swimming equipment**: Fins, kickboard, paddles, pull buoy, snorkel\n\n#### Duration Types\n\n- **Time \u0026 distance**: Standard interval durations\n- **Calorie-based**: Steps ending after burning specified calories\n- **Power-based**: Steps ending based on power thresholds (watts)\n- **Heart rate conditionals**: Steps ending based on HR thresholds (bpm)\n- **Repeat conditionals**: Repeat blocks until time/distance/calories/HR/power targets reached\n\n### Known Limitations\n\n- **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!\n\n---\n\n## 📚 Documentation\n\nComprehensive documentation is available in the `/docs` directory:\n\n- **[Getting Started](./docs/getting-started.md)** - Installation, basic usage, and quick examples for both library and CLI\n- **[Architecture](./docs/architecture.md)** - Hexagonal architecture, ports \u0026 adapters pattern, and design principles\n- **[Testing](./docs/testing.md)** - Testing strategy, TDD workflow, and coverage requirements\n- **[Deployment](./docs/deployment.md)** - CI/CD pipeline, GitHub Pages deployment, and npm publishing\n- **[Contributing](./CONTRIBUTING.md)** - Contribution guidelines, development workflow, and code standards\n- **[KRD Format](./docs/krd-format.md)** - Complete specification of the Kaiord Representation Definition format\n- **[AI Agents](./AGENTS.md)** - Guidance for AI-assisted development\n\n---\n\n## 🧩 Tech Stack\n\n| Layer           | Tooling                            |\n| --------------- | ---------------------------------- |\n| Core            | TypeScript, tsup, Zod              |\n| CLI             | yargs                              |\n| Web App         | React, Zustand, Tailwind, Radix UI |\n| Testing         | Vitest, Playwright                 |\n| Package manager | pnpm                               |\n\n---\n\n## 🏗 Monorepo Layout\n\n```\nkaiord/\n├─ packages/\n│  ├─ core/                → domain types, schemas, ports \u0026 use cases\n│  ├─ fit/                 → Garmin FIT format adapter\n│  ├─ tcx/                 → Training Center XML adapter\n│  ├─ zwo/                 → Zwift ZWO format adapter\n│  ├─ garmin/              → Garmin Connect API adapter\n│  ├─ cli/                 → command-line interface\n│  ├─ mcp/                 → MCP server for AI/LLM integration\n│  └─ workout-spa-editor/  → web application (https://pablo-albaladejo.github.io/kaiord)\n├─ docs/   → documentation\n├─ LICENSE\n├─ README.md\n└─ pnpm-workspace.yaml\n```\n\n---\n\n## 🚀 Quick Start\n\n### Try the Web App\n\n**[Launch Workout Editor →](https://pablo-albaladejo.github.io/kaiord)**\n\nCreate and edit workouts visually in your browser. No installation required.\n\n### Use the Library\n\n```bash\npnpm install\npnpm -r build\npnpm -r test\n\n# Example usage\npnpm kaiord --help\n```\n\nFor detailed installation instructions and usage examples, see the **[Getting Started Guide](./docs/getting-started.md)**.\n\n---\n\n## 🚀 CI/CD Pipeline\n\nKaiord uses GitHub Actions for continuous integration and deployment:\n\n- **Automated Testing**: Multi-version testing on Node.js 22.x (Maintenance LTS) and 24.x (Active LTS)\n- **Code Quality**: ESLint, Prettier, and TypeScript strict mode validation\n- **Release Automation**: Changesets for version management and npm publishing\n- **Security**: Weekly dependency vulnerability audits\n\nFor complete CI/CD documentation, deployment guides, and npm publishing instructions, see **[Deployment](./docs/deployment.md)**.\n\n### Contributing\n\nTo contribute to Kaiord:\n\n1. **Fork and clone** the repository\n2. **Create a feature branch**: `git checkout -b feature/my-feature`\n3. **Make your changes** following the code style guidelines\n4. **Add a changeset**: `pnpm exec changeset` (for version-worthy changes)\n5. **Test locally**: `pnpm -r test` and `pnpm -r build`\n6. **Submit a PR**: All checks must pass before merging\n\nFor detailed contribution guidelines, development workflow, and code standards, see **[Contributing](./CONTRIBUTING.md)**.\n\n---\n\n## 📚 References \u0026 Resources\n\n### Format Specifications\n\n- [Garmin FIT SDK (JavaScript)](https://github.com/garmin/fit-javascript-sdk) - Official FIT protocol implementation\n- [FIT Workout Files Cookbook](https://developer.garmin.com/fit/cookbook/encoding-workout-files/) - Guide to encoding workout files\n- [FIT File Types: Workout](https://developer.garmin.com/fit/file-types/workout/) - Workout file type specification\n- [Training Center XML (TCX)](https://en.wikipedia.org/wiki/Training_Center_XML) - Garmin's XML-based format\n- [TCX Schema (XSD)](https://www8.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd) - Official Garmin TCX schema definition\n- [Zwift Workout Format (ZWO)](https://zwift.com) - Zwift's XML-based workout format\n\n---\n\n## ❤️ Support\n\nIf you find Kaiord useful, consider supporting its development:\n\n- ⭐ **Star this repo** to help others discover it\n- 💖 **[Sponsor on GitHub](https://github.com/sponsors/pablo-albaladejo)**\n- ☕ **[Buy me a coffee](https://buymeacoffee.com/pabloalbaladejo)**\n\nYour support helps maintain and improve Kaiord for the fitness community!\n\n---\n\n## 📜 License\n\nMIT © 2025 Pablo Albaladejo\nSee [LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpablo-albaladejo%2Fkaiord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpablo-albaladejo%2Fkaiord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpablo-albaladejo%2Fkaiord/lists"}