README.md

# Helios agent package

Use Helios to build workout plans, select exercises, review progress, prepare reusable meals, and set daily nutrition targets. Linked notes add context when needed. The package has one skill and a remote MCP connection. Helios stores records and checks account access on its hosted service. Do not put passwords or tokens in package files or chat.

The MCP address is `https://api.getheliosapp.com/mcp`. Public discovery confirmed this address on 1 October 2026. Package validation does not prove host sign-in or task support. The release must pass those checks before public use.

## Claude Code

Use Claude Code 2.1.224 or later for the HTTPS archive route. Obtain the published HTTPS catalog URL from the Helios release notice. Set `HELIOS_CATALOG_URL` to that exact URL. Then run:

```sh
claude plugin marketplace add "$HELIOS_CATALOG_URL"
claude plugin install helios@helios
claude plugin details helios
```

Start a new session. Open `/mcp`, select Helios, and complete browser sign-in. Grant only the access needed for your task. Enter `/helios:helios`, then ask: "List my Helios workout plans."

To update, run `claude plugin update helios@helios`, then start a new session. Third-party automatic updates are off by default. You can enable them in the marketplace controls under `/plugin`. A new release must have a higher package version. An unchanged version will not update an installed copy. See the [Claude Code update guide](https://code.claude.com/docs/en/plugins/host-marketplace).

For a local test, run `claude plugin validate ./plugins/helios`, then `claude --plugin-dir ./plugins/helios`. The installed plugin command is `/helios:helios`.

## Codex local test

Copy the exported package to `plugins/helios` in a disposable project. Add `.agents/plugins/marketplace.json` at that project's root:

```json
{
  "name": "helios-local",
  "plugins": [{
    "name": "helios",
    "source": {"source": "local", "path": "./plugins/helios"},
    "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
    "category": "Other"
  }]
}
```

Open the project in a supported local client. Install and enable Helios in Plugins. Start a new chat and complete the connection flow. Use `$helios` or "List my Helios workout plans." Record the client version and result. Local plugin support can differ by surface. See the [OpenAI package guide](https://developers.openai.com/plugins/build/plugins).

## ChatGPT and Claude chat

The public directory routes need separate approval. A local install or a Claude Code catalog does not create a consumer chat listing. After approval, install the listed Helios plugin and connect your Helios account. Use the label shown by that host. Claim `@helios` only after that entry appears and passes a task check.

OpenAI accepts the compatibility ZIP with MCP and skills. Claude chat uses the package-only repository and connector route. The application repository stays private. See [OpenAI Claude package submission](https://developers.openai.com/plugins/guides/submit-claude-plugin) and [Claude plugin submission](https://claude.com/docs/plugins/submit).

## Task and error checks

1. Read plans and exercises from your synthetic test account. A read-only grant must not expose writes.
2. Review a new workout plan. Ask to save that exact plan. Read it again and check its saved revision.
3. Edit the plan with its current revision. Reject a stale revision without a partial change.
4. Repeat an uncertain write with the same request ID and arguments. Check its receipt and saved record.
5. Revoke the connection in Helios. A new call must fail. Reconnect and verify that the old tokens still fail.
6. Test an upgrade from the prior hosted ZIP in a separate client profile. Check the installed version and rerun the read task.

Record each check as passed, failed, or pending. Never use customer records for these checks. Run the five positive and three negative submission cases for workouts, progress, meals, targets, recorded history, and access boundaries. These are required checks, not evidence of completed host acceptance. Record live workouts and food in the app; MCP manages plans, presets, targets, and supported corrections.