[Feature] Declarative "Custom Provider": bring-your-own endpoint + JSONPath field mapping

[lkangd]

TL;DR

Let users define their own provider in config.json: a custom endpoint (URL + auth) plus a small JSONPath-style mapping that translates that provider's usage response into CodexBar's RateWindow / ProviderCostSnapshot / ProviderIdentitySnapshot fields — no Swift code, no fork, no release wait.

Why I'm filing this

I self-host an LLM gateway. CodexBar can't see it. And I'm far from alone — the issue tracker tells the story. Every few weeks someone files "please add my provider":

• Add supplier canopywave.com #1593 (canopywave), Add supplier - qoder #1590 (qoder), Add LongCat usage provider #1697 (LongCat), [codex] Add Doubao coding plan usage #1727 (Doubao), [codex] Add Sakana AI usage provider #1728 (Sakana), Feature Request: XAI Platform #1712 (xAI), Perplexity API Error: 404 #1592 (Perplexity), Enhancement: Add Nous Research / Hermes Agent as a provider #1367 (Nous Research / Hermes), Groq Peronal Free Tier API key #1616 (Groq free tier), feature request: antigravity (add weekly limit) #1541 (antigravity), Add Kimi Code API usage source #1424 / Add Kimi Code API-key usage support #1412 (Kimi), Add Alibaba Token Plan provider #1098 (Alibaba token plan), feat: add CheapestInference provider #547 (CheapestInference)…

Each is real demand, and each — today — needs a whole Swift module: ProviderDescriptor + SettingsReader + UsageFetcher + ProviderImplementation + an SVG icon + localization. That's right for first-class providers. For the long tail of self-hosted / in-house / boutique gateways it's a bottleneck for everyone: the user can't see their quota, and the maintainer drowns in one-off integrations nobody can really maintain.

There's already a beautiful template: #264 → LLM Proxy (LLMProxyUsageFetcher) and LiteLLM. Both already take base URL + API key and hit a known schema. The only thing keeping them from being generic is that the endpoint path and field extraction are hardcoded in Swift (Decodable CodingKeys + a hand-written toUsageSnapshot()). Even the two quota_groups shapes (array vs keyed) are special-cased in code.

That hand-coded mapping is exactly the seam a declarative provider would fill.

What I'd love

A type: "custom" provider where a user supplies:

1. The request — method, path, auth header/env, optional body. (Ask No rate limits event #1: "fill in a custom usage/quota query".)
2. The mapping — JSONPath (or dot-path) expressions pointing into that provider's response, bound to CodexBar's existing model fields. (Ask Homebrew #2: "a return-data path transformer → usage / balance / resetsAt".)

Sketch

{
  "providers": {
    "acme-gateway": {
      "type": "custom",
      "label": "Acme Gateway",
      "icon": "proxy",                 // built-in fallback, or path to a user svg
      "baseURL": "https://gw.acme.io",
      "auth": { "header": "Authorization", "prefix": "Bearer ", "env": "ACME_GATEWAY_API_KEY" },
      "usage": { "method": "GET", "path": "/v1/quota" },
      "mapping": {
        "usedPercent":      "$.quota.used_pct",
        "remainingPercent": "$.quota.remaining_pct",
        "resetsAt":         "$.quota.reset_at",        // ISO-8601
        "windowMinutes":    "$.quota.window_min",
        "costUsed":         "$.spend.usd",
        "costCurrency":     "USD",
        "costPeriod":       "Approx. spend",
        "organization":     "$.plan.name",
        "loginMethod":      "$.credits.balance_str"
      }
    }
  }
}

Field binding (reuses types CodexBar already has)

CodexBar field	Type	Example path
RateWindow.usedPercent	number 0–100	$.quota.used_pct
RateWindow.remainingPercent	number 0–100	$.quota.remaining_pct
RateWindow.resetsAt	ISO-8601 date	$.quota.reset_at
RateWindow.windowMinutes	number	$.quota.window_min
ProviderCostSnapshot.used	number	$.spend.usd
ProviderIdentitySnapshot.accountOrganization	string	$.plan.name
ProviderIdentitySnapshot.loginMethod	string	$.credits.balance_str

Fill in only the fields the endpoint exposes; the rest stay empty, same as any provider with sparse data.

Why this is low-risk

• Opt-in. Nothing happens until a type: "custom" entry exists. All 53 existing providers keep working unchanged.
• Reuses the existing model. Output is the same UsageSnapshot the menu already renders — no new UI primitives.
• Reuses existing security posture. Base-URL validation, keychain storage, and the HTTPS-only hardening already in place for LLM Proxy / LiteLLM / Azure apply directly.
• Cuts maintainer load. The "add my provider" tail routes to a docs page instead of a Swift PR.

Alternatives considered

• Fork + hand-write a provider each time. Works, but doesn't scale (one gateway = one fork to chase across releases) and helps nobody else.
• Just use LLM Proxy / LiteLLM. Great if a gateway happens to mirror those exact schemas — most self-hosted ones don't, and reshaping a server's response to match CodexBar is backwards.

Open questions (happy to defer)

• Expression engine. Full JSONPath, a dot-path subset, or jq-lite? I'd start with dot-path + a couple of coercion hints (ISO-8601 date, percent) and grow.
• Refresh semantics. Expose POST/force-refresh like LLM Proxy, or keep custom providers poll-only?
• Multi-window. Array of mappings for providers exposing session/weekly/monthly in one call (mirrors extraRateWindows).

Happy to prototype or draft the docs. 🙌

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 24, 2026, 4:25 AM ET / 08:25 UTC.

Summary
Current-main inspection shows this is still a real feature request: provider IDs, config, endpoint overrides, and response mapping remain tied to concrete Swift provider implementations. The request also needs maintainer product/privacy sign-off under VISION.md, so it should stay open rather than be queued as an automated fix.

Reproducibility: not applicable. this is a feature request for a new custom-provider configuration mode, not a failure in existing behavior. Source inspection confirms current main only supports known provider IDs and provider-specific config fields.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
Maintainers need to decide the product and privacy boundary before implementation; this should not be an automatic fix PR yet.

Review details

Best possible solution:

Keep this as the canonical design discussion and, if maintainers accept it, implement a bounded MVP with strict HTTPS/auth validation, a small typed dot-path mapper, sparse UsageSnapshot output, and focused config/parser/security tests.

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

Not applicable: this is a feature request for a new custom-provider configuration mode, not a failure in existing behavior. Source inspection confirms current main only supports known provider IDs and provider-specific config fields.

Is this the best way to solve the issue?

Unclear pending maintainer direction: the proposed declarative provider model is plausible and aligned with reducing long-tail provider churn, but it is not yet proven to be the best boundary for auth, endpoint validation, expression syntax, and UI/config compatibility.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A custom provider framework would broaden configurable network/auth behavior and response parsing, so maintainers need to set a privacy/security boundary before implementation.
• The feature cuts across config decoding, endpoint validation, provider registry/runtime, Settings UI, docs, and parser tests; a narrow single-provider-style fix would not be enough.

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

Label changes

Label changes:

• add P3: This is a useful but speculative provider extensibility feature rather than a broken current workflow.
• add impact:auth-provider: The request is about configurable provider routing, endpoint authentication, and usage-data mapping.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: This is a useful but speculative provider extensibility feature rather than a broken current workflow.
• impact:auth-provider: The request is about configurable provider routing, endpoint authentication, and usage-data mapping.

Evidence reviewed

What I checked:

• VISION.md sign-off boundary: VISION.md says provider coverage is aligned with CodexBar, but new features and changes affecting provider auth, data storage, or user privacy need sign-off. (VISION.md:3, ada3660e9d61)
• Provider enum is closed over known providers: UsageProvider is a fixed Codable enum of known provider IDs and has no custom provider case. (Sources/CodexBarCore/Providers/Providers.swift:5, ada3660e9d61)
• Config has no request or mapping schema: ProviderConfig requires a UsageProvider id and exposes fixed shared fields; it has no method/path/body/auth-header or JSONPath/dot-path mapping fields. (Sources/CodexBarCore/Config/CodexBarConfig.swift:96, ada3660e9d61)
• Provider descriptor registry is Swift-defined: ProviderDescriptorRegistry maps each UsageProvider case to a concrete descriptor and preconditions when a descriptor is missing, so current provider support is not dynamically declared from config. (Sources/CodexBarCore/Providers/ProviderDescriptor.swift:55, ada3660e9d61)
• Docs only document fixed provider fields: Configuration docs document provider-specific fields and show LLM Proxy/LiteLLM as fixed provider IDs using apiKey plus enterpriseHost, not arbitrary endpoints or response mappings. (docs/configuration.md:47, ada3660e9d61)
• LLM Proxy mapping is hardcoded: LLMProxyUsageSnapshot maps quota-stats fields into UsageSnapshot in Swift, including provider identity fixed to .llmproxy. (Sources/CodexBarCore/Providers/LLMProxy/LLMProxyUsageFetcher.swift:49, f380287041b8)

Likely related people:

• Peter Steinberger: Blame for ProviderConfig, UsageProvider, ProviderDescriptorRegistry, and the LLM Proxy/LiteLLM mapping code points to f380287 in this checkout, making him the strongest routing candidate for framework-level provider design. (role: central provider/config owner in current history; confidence: medium; commits: f380287041b8; files: Sources/CodexBarCore/Config/CodexBarConfig.swift, Sources/CodexBarCore/Providers/Providers.swift, Sources/CodexBarCore/Providers/ProviderDescriptor.swift)
• BAKEZQ: Recent provider/config-area history includes Support z.ai BigModel team usage, which is adjacent to provider auth/settings/snapshot mapping work even though it does not own the custom provider request. (role: recent adjacent provider contributor; confidence: low; commits: 2435c93453fe; files: Sources/CodexBarCore/Providers, Sources/CodexBar/Providers)
• Yuxin Qiao: Recent provider-area history includes Antigravity quota lane work, another nearby provider parser/mapping surface relevant to routing discussions. (role: recent adjacent provider contributor; confidence: low; commits: 388ee1417386; files: Sources/CodexBarCore/Providers, Sources/CodexBar/Providers)
• Lucas Fonseca Mundim: Recent provider-area history includes a Mistral auth/cookie import fix, adjacent to the auth/privacy concerns a custom provider framework would raise. (role: recent adjacent provider contributor; confidence: low; commits: c6399fedc4a8; files: Sources/CodexBarCore/Providers, Sources/CodexBar/Providers)

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.