Feature Request: Add Charm Hyper (hyper.charm.land) as a provider

[JavaGT]

Feature Request: Add Charm Hyper (hyper.charm.land) as a provider

Summary

Would love to see CodexBar support Charm Hyper — Charm's coding-optimized inference provider (official provider for the Crush agent). It uses a Hypercredit-based billing model (1 Hypercredit = 5¢) with free monthly grants, daily-refreshing subscriptions, and prepaid bundles that never expire.

The web dashboard shows a reset panel ("Plan / Shred / Next Hypercredit refresh in 13 hours"), which lines up with CodexBar's per-provider reset-countdown feature.

Investigation findings

Sharing what I turned up while looking into feasibility. Not prescribing any particular implementation — just recording the evidence so a maintainer can pick scope.

Endpoints probed (authenticated with HYPER_API_KEY):

Path	Status	Notes
GET /v1/models	200 (public)	OpenAI-shaped list with per-model pricing.input/pricing.output/cache_create/cache_hit
GET /v1/credits	200	Returns {"balance": <int>} only — 21 bytes, no reset_at, no plan, no limit
GET /v1/me, /v1/usage, /v1/account, /v1/subscription, /v1/plan, /v1/key	404	No account/usage/plan endpoints on the API-key side
GET /api/*	404	No separate dashboard API surface

Chat completion response (POST /v1/chat/completions) carries metadata in two places:

• Body: usage.remaining.hypercredits (float) and usage.cost.usd / usage.cost.hypercredits per response
• Headers: x-ratelimit-limit-day, x-ratelimit-limit-hour, x-ratelimit-remaining-day, x-ratelimit-remaining-hour (request windows, not Hypercredit refresh)

Dashboard "Plan / Shred / Next Hypercredit refresh in 13h" panel is server-rendered HTML behind cookie auth, not exposed via any API-key endpoint I could find.

Auth conventions:

• HYPER_API_KEY env var — matches Crush and @charmland/pi-hyper-provider conventions
• OAuth subscription flow also exists (used by Crush), but API key is the simpler path

Operator: Charmbracelet, Inc., Brooklyn NY — first-party operator, not a reseller (relevant to CodexBar's hosted-relay eligibility clause in docs/provider.md).

Reference implementations in the wild:

• charmbracelet/crush/internal/agent/hyper/provider.go — Go; calls /v1/credits for balance, also extracts remaining.hypercredits from chat response metadata
• @charmland/pi-hyper-provider (TypeScript) — Pi extension; same /credits endpoint, plus OAuth + team-name display

Existing CodexBar providers with similar shape

Recorded in case useful as templates — not a recommendation:

• DeepSeek — API-key balance-only, no reset window (docs/deepseek.md)
• Mistral — API-key + browser-cookie hybrid; cookie path scrapes a server-rendered dashboard for plan + reset (docs/mistral.md)
• Codex / Claude cost scan — local JSONL log scanner for per-response cost history

Open questions for the maintainer

• Is balance-only (no reset timer) acceptable for a v1, or is the reset countdown a must-have from day one?
• If reset is needed: is a browser-cookie strategy (Mistral-style) in scope, or should it wait for Charm to expose reset info via API key?
• Any interest in a local Crush-log cost-scan path (reusing the existing Codex/Claude cost-scan architecture), or out of scope?

References

• Hyper landing page: https://hyper.charm.land
• Hyper FAQ: https://hyper.charm.land/faq
• Crush (uses Hyper as official provider): https://github.com/charmbracelet/crush
• Crush's Hyper provider source: https://github.com/charmbracelet/crush/blob/main/internal/agent/hyper/provider.go
• Pi Hyper extension: https://github.com/charmbracelet/pi-hyper-provider
• CodexBar provider authoring guide: https://github.com/steipete/CodexBar/blob/main/docs/provider.md

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 23, 2026, 4:57 PM ET / 20:57 UTC.

Summary
Keep open: Charm Hyper is absent from current main, and the owner-authored combined implementation remains open pending real-account verification.

Reproducibility: not applicable. this requests a new provider capability rather than reporting broken existing behavior.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
Do not start a competing repair: the owner-authored implementation PR already owns the work and needs real-account verification.

Review details

Best possible solution:

Verify the combined provider against a real Charm Hyper account, retain only authenticated paths confirmed by that run, and merge the open implementation before closing this issue.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this requests a new provider capability rather than reporting broken existing behavior.

Is this the best way to solve the issue?

Unclear: the combined session-plus-key design follows the provider architecture, but real-account evidence is still required to confirm the external authentication contract.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The planned session-preferred and API-key fallback behavior lacks real-account verification, so its authenticated endpoint, fallback, and balance presentation remain unproven.

Codex review notes: model internal, reasoning high; reviewed against 63dc1cd520f0.

Label changes

Label justifications:

• P3: This is an optional provider expansion rather than a regression in established behavior.
• impact:auth-provider: The requested capability adds provider authentication and usage-balance retrieval.

Evidence reviewed

What I checked:

• No current-main registration: The current main provider enum and generated first-party descriptor list contain no Charm Hyper provider, so the request is not implemented in the checked-out default branch. (Sources/CodexBarCore/Providers/Providers.swift:17, 63dc1cd520f0)
• Established implementation boundary: Current documentation defines descriptor-owned fetch pipelines, credential adapters, and compile-time first-party registration for provider additions. (docs/provider.md:26, 63dc1cd520f0)
• Current maintainer-owned path: The repository owner linked an open combined PR and stated that it must not merge until a real Charm Hyper account verifies session authentication, API-key fallback, and HC rendering.
• Provider architecture provenance: The provider architecture guidance was last updated by Peter Steinberger in the v0.54.1 release documentation commit, supporting routing to the owner of the current implementation path. (docs/provider.md:26, d6d281e898a0)

Likely related people:

• steipete: Authored the current provider architecture guidance, owns the open combined implementation proposal, and specified the pending live-account verification boundary in the discussion. (role: provider architecture author and current implementation owner; confidence: high; commits: d6d281e898a0; files: docs/provider.md, Sources/CodexBarCore/Providers/Providers.swift, Sources/CodexBarCore/Providers/ProviderManifest.swift)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[akshayprabhu200]

I’m preparing a current-main, balance-only implementation for review. It differs from #2379 in the two material areas found during review: it uses Charm’s documented https://hyper.charm.land/v1/credits endpoint rather than api.hyper.charm.land, and it renders the returned value as an HC balance rather than a generic cost/quota with a zero limit. It will deliberately use an explicit API key only—no browser-cookie probing or OAuth refresh-token reuse—and will include focused regression coverage. This is intended to complement and credit the original work in #2379; please let us know whether the balance-only v1 scope is acceptable.

[steipete]

Update: two implementations are open — #2379 (GET /v1/credits) and #2476 (API-key-only, native HC balance with live proof). We're signing up for Charm Hyper so this can be verified against a real account before anything lands.

Planned shape: support both auth paths rather than choosing one — infer usage from an API key when one is configured, and prefer a signed-in session when available since it exposes more. That matches how most CodexBar providers already work. Keeping this open until it's implemented and verified.

[steipete]

Update on Charm Hyper: Peter is on the Charm Hyper waitlist, so we can't verify either implementation against a live account just yet.

Rather than leave two competing PRs sitting stale, we're combining them into a single new PR that implements both auth paths:

• API key present → infer usage/balance from it (the Add Charm Hyper balance provider #2476 shape).
• Signed-in session → prefer it when available, since it exposes more (the Add Charm Hyper provider #2379 /v1/credits shape).

Both of you will be credited as co-authors on the combined PR. It'll be prepared, tested, and CI-green so it can merge the moment account access comes through and the live behavior checks out. We'll link it here when it's up — thanks for the work and the patience, @JavaGT and @akshayprabhu200.

[steipete]

The combined Charm Hyper PR is up: #2502 — "Add Charm Hyper provider (API key + session)".

It implements both auth paths as planned: a signed-in hyper.charm.land session is preferred in Auto mode (imported from Chrome or supplied as a manual Cookie header), falling back to an explicit API key from configuration, HYPER_API_KEY, or a token account. Balance data stays honest — no inferred plan limit, usage percentage, quota, or reset timestamp — and malformed successful responses fail closed rather than hiding an upstream contract change.

Both of you are recorded as co-authors on the combined commit, and the PR credits #2379 and #2476 explicitly.

It is not merging yet: Peter is on the Charm Hyper waitlist, so nobody has confirmed the behavior against a real account. Once access lands we'll verify session auth, the session-over-key preference and fallback, API/session balance parity, and HC rendering — then it goes in. CI is green apart from one macOS shard still queued.

Keeping #2379 and #2476 open for now so you can review the combined result and flag anything we got wrong about your implementations.