dsh-plugin-ollama-usage
English | 中文
Shows Ollama Cloud account usage (5-hour rolling window / weekly) on the
dsh Web chat page, and provides
a baseURL / credential-mode configuration.
Features
- Shows one panel below the composer in the active session and another on the new-session (hero) page; both carry the same content.
- Reports the
session (5-hour rolling) and weekly windows as percentages, refreshed every 5 minutes by default; credit-plan accounts report a monthly window instead.
- Read-only account usage: it touches no provider configuration and starts no conversations.
- Supports two modes: reusing an existing Ollama key, or using a plugin-specific key.
- When credentials are missing, the endpoint does not offer usage, or the request fails, the panel disappears silently — no placeholder, no error. Only a
200 whose shape cannot be read is called out on the Settings page.
Installation
Requirements: dsh with the web profile (tested with 0.2.0-rc.1), Node ^22.19.0 || >=24.0.0, and a working Ollama Cloud API key.
This package is a dsh bundle: installing it appends the bundle to the profile and applies its patch layer.
Install from GitHub (recommended)
dsh plugin --profile web add github:CJ-SH/dsh-plugin-ollama-usage
Install from a local directory
git clone https://github.com/CJ-SH/dsh-plugin-ollama-usage
dsh plugin --profile web add ./dsh-plugin-ollama-usage
link: installs need one extra step
A plugin installed through link: lives outside the profile, so the profile's install closure has to be linked into the package (idempotent; unnecessary for a materialized install):
npm run link-imports
Do not use npm install to install the @deepseek-ai/schemastery peer — copying it breaks module identity.
The plugin loads at startup, so restart dsh after installing; dsh --profile web --dump-config | grep ollama-usage gives you a pre-flight check.
Usage
The panel appears below the composer in the active session and on the new-session (hero) page:
Active session · below composer session 26% · weekly 6%
New session (hero) the same panel
Configuration baseURL / credential mode / key
The configuration entry point is the "Ollama Usage" page in Settings (the Settings page the plugin registers; merged into the hub panel when the suite hub is installed),
or you can edit the config: block of - id: ollama-usage directly in ~/.dsh/profiles/<profile>/cordis.patch.yml
(fields baseURL / credentialMode / apiKeyEnv).
Uninstall
dsh plugin --profile web remove dsh-plugin-ollama-usage
Technical notes
- Two credential modes: credential mode (
reference, the default) reuses an existing apiKeyEnv (default OLLAMA_API_KEY) and this plugin cannot write to it; key mode (direct) writes only its own reference, OLLAMA_USAGE_API_KEY.
- Quota comes from
GET {baseURL}/api/balance (Authorization: Bearer <key>): legacy plans report remaining_percent and resets_at for session/weekly, and the panel shows the used percentage and the absolute reset time; credit plans report a monthly allowance balance and are shown as a monthly window.
- Since 2026-10
/api/usage returns only per-day request / cost / token buckets and no per-model breakdown (the official API has no successor endpoint for it).
- The slots and containers are dsh-internal contracts and a dsh upgrade may move them; a panel that does not render is itself the failure mode (no placeholder, no error).
- Settings and credentials survive uninstall; remove the
- id: ollama-usage block from the profile patch by hand if you want them gone.
Further reading
Contracts, troubleshooting, and internals are in docs/design-notes.md.
License
MIT © 2026 HenTaiCJN
Ollama is a product of Ollama Inc.; this plugin is not affiliated with it and only calls its public API.
