Pi COROS Running Agent

A Pi package that connects Pi to a COROS Running Agent backend.

This repo follows the same style as many Pi integration packages: it contains a small extension plus a skill, while the actual service runs separately.

Pi TUI
  -> pi-coros-running-agent package
     -> extension: registers the coros_running_agent tool
     -> skill: teaches Pi when to use the tool
  -> COROS Running Agent HTTP API
  -> COROS MCP + RAG + memory + workout report workflow

What This Package Does

• Adds a coros_running_agent tool to Pi.
• Adds a /coros command for direct questions.
• Adds a coros-running-agent skill for better natural-language routing.
• Keeps COROS OAuth tokens, FIT files, RAG sources, personal memory, and private data in your own backend.

This package does not talk to COROS directly. It calls a backend that exposes POST /api/chat.

Package Structure

pi-coros-running-agent/
├── extensions/
│   └── pi/
│       └── index.ts
├── skills/
│   └── coros-running-agent/
│       └── SKILL.md
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

Requirements

• Pi Agent
• Node.js 20+
• A running COROS Running Agent backend

The backend should support:

POST /api/chat
content-type: application/json

{
  "message": "Analyze my latest workout",
  "session_id": "pi-coros"
}

Minimum response:

{
  "message": "..."
}

Optional response fields such as capability, confidence, tools, graph_steps, citations, and memory are shown as metadata.

Install

From GitHub:

pi install git:github.com/Noah-wang/pi-coros-running-agent

Then start Pi normally.

From npm, after the package is published:

pi install npm:pi-coros-running-agent

For local development:

git clone https://github.com/Noah-wang/pi-coros-running-agent.git
cd pi-coros-running-agent
npm install
npm run check

Run directly without installing:

COROS_RUNNING_AGENT_URL=http://127.0.0.1:8787 \
pi -e ./extensions/pi/index.ts

Configuration

COROS_RUNNING_AGENT_URL=http://127.0.0.1:8787
COROS_RUNNING_AGENT_TOKEN=
COROS_RUNNING_AGENT_SESSION_ID=pi-coros

COROS_RUNNING_AGENT_TOKEN is optional. If set, the extension sends:

Authorization: Bearer <token>

Usage

Ask naturally:

Analyze my latest workout and tell me what I should do next.

Or use the direct command:

/coros Analyze my latest workout

Other examples:

List my recent COROS activities.
Show my personal bests.
Use my running knowledge base to explain why my marathon is much slower than my half marathon.
Find my Los Angeles Marathon photos.
Build a training plan for my next marathon goal.

Why It Is Split This Way

pi-coros-running-agent is the Pi integration package.

coros-running-agent is the backend that owns:

• COROS MCP access
• LLM configuration
• RAG and embeddings
• long-term memory
• FIT archive
• race photos
• report workflow

This split keeps the Pi package easy to review and install, while private data stays outside the package.

Security

Do not commit:

• .env
• COROS OAuth tokens
• API keys
• FIT files
• RAG source PDFs
• personal memory files
• race photos

Only configure backend URLs and tokens through environment variables.

Publish to npm and pi.dev

pi.dev/packages discovers Pi packages from npm. There is no separate manual upload form.

To make this package appear in the Pi package gallery:

1. Keep pi-package in package.json keywords.
2. Keep the pi manifest in package.json:

{
  "pi": {
    "extensions": ["./extensions/pi/index.ts"],
    "skills": ["./skills"]
  }
}

3. Verify the package:

npm install --ignore-scripts
npm run check
npm pack --dry-run

4. Publish to npm:

npm login
npm publish --access public

5. Test install from Pi:

pi install npm:pi-coros-running-agent

The Pi gallery may take some time to index the npm package.

For later updates:

npm version patch
git push --follow-tags
npm publish --access public