{
  "markdown": "# Kaiord — Open-Source Health & Fitness Data Framework\n\n**[kaiord.com](https://kaiord.com)** | [Editor](https://kaiord.com/app/) | [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[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.pablo--albaladejo%2Fkaiord-8A2BE2)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.pablo-albaladejo/kaiord)\n[![Glama MCP server](https://glama.ai/mcp/servers/@pablo-albaladejo/kaiord/badges/score.svg)](https://glama.ai/mcp/servers/@pablo-albaladejo/kaiord)\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 & 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.). Published in the [official MCP registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.pablo-albaladejo/kaiord) as `io.github.pablo-albaladejo/kaiord`.\n- **[Workout Editor](https://kaiord.com/app/)**: a web application to create and edit workout files visually.\n\n---\n\n## ✨ Features\n\n- **[Visual Workout Editor](https://kaiord.com/app/)** - 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 & 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 & 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## 🔒 Local-first architecture\n\nKaiord is local-first: your data lives on your device, because there is no Kaiord server to send it to. There are no accounts and no backend.\n\n- **Storage is your browser's IndexedDB.** The [Workout Editor](https://kaiord.com/app/) persists every workout, template, profile, and setting in a local Dexie.js / IndexedDB database (`new KaiordDatabase()` in [`dexie-database.ts`](./packages/workout-spa-editor/src/adapters/dexie/dexie-database.ts)), and the UI reads it reactively through `useLiveQuery`. Nothing is written to a remote database — see the \"Persisted data → Dexie\" rule in [State Management](./CLAUDE.md).\n- **Conversions run entirely on your machine.** FIT / TCX / ZWO / GCN ↔ KRD conversion happens in-process — client-side in the editor ([`import-workout-formats.ts`](./packages/workout-spa-editor/src/utils/import-workout-formats.ts), [`export-workout-formats.ts`](./packages/workout-spa-editor/src/utils/export-workout-formats.ts)) or locally in the [`@kaiord/cli`](./packages/cli). Files never leave your device to be converted.\n- **Sync is opt-in and goes to _your_ cloud.** Data leaves the device only if you connect Google Drive. The [cloud-sync adapter](./packages/workout-spa-editor/src/adapters/cloud-sync) uses the Google Identity Services `drive.appdata` scope, so synced data lands in your own Drive's app folder; the access token lives only in memory for the session and is never persisted by Kaiord.\n- **Integrations use _your_ logged-in session — no credential proxy.** Garmin, WHOOP, and Train2Go connect through browser-extension \"bridges\" ([`garmin-bridge`](./packages/garmin-bridge), [`whoop-bridge`](./packages/whoop-bridge), [`train2go-bridge`](./packages/train2go-bridge)) that piggyback on your existing browser session. Per [`openspec/specs/adapter-contracts/spec.md`](./openspec/specs/adapter-contracts/spec.md), a bridge \"SHALL NOT store, transmit, or manage user credentials\"; authentication is \"delegated entirely to the browser's cookie jar.\" No third-party server proxies your credentials or your data.\n- **Works offline.** Because all logic and storage are client-side, the editor keeps working with no network connection once loaded.\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 & 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, tsdown, 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 & 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://kaiord.com/app/)\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://kaiord.com/app/)**\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, CodeQL static analysis, and automated dependency updates\n\nFor complete CI/CD documentation, deployment guides, and npm publishing instructions, see **[Deployment](./docs/deployment.md)**.\n\n### Mechanical invariant guards\n\nBeyond linting, the repo enforces its architecture and conventions with **60+ purpose-built guard scripts** under [`scripts/`](./scripts/README.md), 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:\n\n- **Hexagonal architecture** — layer purity, adapter isolation, and the `packages/core/src/` directory allowlist (`check-architecture.mjs`)\n- **Package dependency graph** — every `@kaiord/*` dependency must match the spec table (`check-package-deps.mjs`)\n- **Test conventions** — `should `-prefixed titles and Arrange/Act/Assert structure on every test (`check-test-title-should.mjs`, `check-test-aaa.mjs`)\n- **Privacy** — no runtime values interpolated into toasts or console logs (`check-no-pii-leakage.mjs`)\n- **State discipline** — no Zustand store writes persistence directly (`check-no-zustand-writethrough.mjs`)\n- **Spec hygiene** — OpenSpec format, archive dates, and auto-generated indexes stay in sync (`check-spec-format.mjs`, `check-archive-*.mjs`)\n\nIf a rule matters here, a script enforces it — documentation describes the rules, but the guards are what make them true.\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 & 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\nBuilt by **[Pablo Albaladejo](https://pabloalbaladejo.com)**\n\n---\n\n## 📜 License\n\nMIT © 2025 Pablo Albaladejo\nSee [LICENSE](./LICENSE) for details.\n",
  "bytes": 11519,
  "sha": "3b219caf40a586e6366544262dd98df6f5dd71ae292f975ac6132669ba6ff02d",
  "repo_slug": "pablo-albaladejo/kaiord",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pablo_albaladejo_kaiord_64382abb/readme"
}