workbuddy-cli-model-bridge
Skill787 starsChanged 4 months agoMITView on GitHub
Install, audit, repair, and manage a loopback-only CLIProxyAPI
- Installs packages
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- codex-cli-model-bridgeSkill
- codex-doctorSkill
- codex-external-handoffSkill
- codex-handoffSkill
- codex-image-genSkill
- codex-model-routing-teamSkill
- codex-skill-adminSkill
- codex-theme-studioSkill
- enterprise-clone-builderSkill
- gpt56-sol-pro-consultSkill
- html-expressSkill
- leadbookSkill
- light-plan-and-workSkill
- scholar-stickersSkill
- skill-open-sourcerSkill
- web-clipperSkill
- wechat-article-searchSkill
- wechat-stylerSkill
- wxmp-article-harvesterSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. About 0 are common, 17 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 37
Read the JSON findings. The audit redacts secrets and detects:
- Distinctive: line 45
Treat an existing CLI login as a discovery signal.
- Distinctive: line 67
Keep a healthy existing installation in place.
- Distinctive: line 83
Do not authorize unrelated Providers merely because they are bundled.
- Very specific: line 107
Do not use --skip-probes for a live setup.
- Distinctive: line 109
When the user explicitly requests Fast mode and no Fast model appears, read the Fast-model section in troubleshooting.md.
- Very specific: line 117
Run the audit again. If WorkBuddy is already open, inspect its current main-thread log for a models.json changed or Loaded custom models …
- Distinctive: line 129
Never include API keys, OAuth URLs containing one-time codes, token file contents, or raw request bodies.
- Very specific: line 135
Run audit and distinguish proxy-down, missing key, missing OAuth, unavailable model, Provider quota, and WorkBuddy-cache failures.
- Distinctive: line 136
Start or repair the existing service before reinstalling anything.
- Distinctive: line 140
Verify a real text request and every declared optional capability.
- Distinctive: line 142
Do not rotate the WorkBuddy API key merely because a Provider OAuth session changed.
- Distinctive: line 144
Read troubleshooting.md for failure classification and rollback guidance.
- Distinctive: line 176
Read security-boundaries.md before changing service exposure, credentials, or adding a local adapter.
- Distinctive: line 180
Use only accounts the user owns and respect Provider subscription terms and rate limits.
- Distinctive: line 181
Never implement ban evasion, account sharing, automated block reset, token extraction, or hidden traffic cloaking.
- Distinctive: line 183
Treat Provider manifests as code: validate their source and inspect local overrides before executing login flags.
- Distinctive: line 192
every enabled optional capability passed its probe
- Distinctive: line 193
every registered model has sourced input/output limits and passed the bounded output-limit probe
- Distinctive: line 198
If any gate remains unproven, report the model as unverified rather than declaring success.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
WorkBuddy CLI Model Bridge
Turn supported CLI subscriptions into verified WorkBuddy custom-model entries through CLIProxyAPI. Use the bundled script for discovery, installation, OAuth handoff, capability probes, and idempotent WorkBuddy updates. Keep model claims tied to real probes; a model name or marketing page is not evidence that a particular proxy route preserves the capability.
Resolve the Skill directory
Resolve this loaded Skill's directory and use its absolute path as <skill-dir>. Do not assume a specific installation root.
The deterministic entry point is:
python3 <skill-dir>/scripts/bridge.pyDefault workflow
1. Audit before changing anything
python3 <skill-dir>/scripts/bridge.py auditRead the JSON findings. The audit redacts secrets and detects:
- Homebrew, CLIProxyAPI, active config, bind address, and proxy reachability
- WorkBuddy initialization and existing model count
- bundled and local Provider manifests
- CLI executables and login signals without reading token contents
- CLIProxyAPI auth-file counts without exposing account names
Treat an existing CLI login as a discovery signal. CLIProxyAPI may still require its own OAuth grant; do not copy another CLI's token file.
2. Bootstrap CLIProxyAPI when required
Preview:
python3 <skill-dir>/scripts/bridge.py bootstrapApply the plan when the user asked to install, configure, repair, or converge the bridge:
python3 <skill-dir>/scripts/bridge.py bootstrap --applyThe request to set up the bridge authorizes reversible Homebrew installation, loopback service startup, a dedicated random proxy client key, secure local state, and timestamped backups. Pause only when:
- Homebrew itself is missing and its installer requires administrator interaction
- an existing proxy listens beyond loopback; explain the remote-client impact before using
--allow-rebind-local - an overlapping deployment or config conflict makes ownership ambiguous
Keep a healthy existing installation in place. Prefer official Homebrew installation for a new macOS setup.
3. Authorize only relevant Providers
Bundled OAuth Provider IDs are codex, xai-grok, and antigravity. Authorize one when the user requested it or the audit found its CLI/login signal and CLIProxyAPI has no matching auth/model route.
python3 <skill-dir>/scripts/bridge.py authorize codex
python3 <skill-dir>/scripts/bridge.py authorize xai-grok
python3 <skill-dir>/scripts/bridge.py authorize antigravityThe command delegates to CLIProxyAPI's native OAuth flag. Tell the user to approve the browser page, then continue automatically. Never paste, print, transform, or reuse OAuth tokens. Secure resulting auth JSON files to owner-only permissions.
Bundled glm-coding is a Coding Plan API-key Provider, not OAuth. Do not run authorize glm-coding. Follow glm-coding-plan.md: add the official coding /paas/v4 route to CLIProxyAPI, then sync --providers glm-coding. Do not use 智谱清言 website login.
Do not authorize unrelated Providers merely because they are bundled.
4. Probe and synchronize WorkBuddy
Pass only the relevant Provider IDs:
python3 <skill-dir>/scripts/bridge.py sync --providers codex,xai-grok,glm-coding --applyThe sync command:
- fetches the live
/v1/modelslist - selects recommended chat/agent models from Provider manifests
- probes text, SSE streaming, tools, images, and reasoning controls where declared
- resolves token limits by exact model ID, using Provider-declared catalogs before sourced manifest metadata
- refuses to register a model with an unknown input/output limit or a rejected output-limit probe
- skips models whose text or streaming probes fail
- downgrades optional capability flags when their probes fail
- backs up and atomically updates
~/.workbuddy/models.json - preserves manual entries and stale managed entries
- refuses to overwrite a manual entry with the same model ID
- records ownership separately under
~/.config/workbuddy-cli-model-bridge/
Do not use --skip-probes for a live setup. That option exists for deterministic offline tests only.
When the user explicitly requests Fast mode and no Fast model appears, read the Fast-model section in troubleshooting.md. A Fast alias needs both a distinct CLIProxyAPI route and verified priority semantics; never relabel an ordinary model as Fast.
A reasoning probe verifies control compatibility. It cannot expose private chain of thought. For teaching or screen recording, ask the model to emit a deliberate problem decomposition as normal answer content.
WorkBuddy represents each custom model as a separate entry. This Skill registers verified entries; it does not change the user's currently selected conversation model.
5. Verify the application consumed the change
Run the audit again. If WorkBuddy is already open, inspect its current main-thread log for a models.json changed or Loaded custom models config event. If no reload event appears, ask the user to reopen model settings or start a new conversation; do not rewrite the same config repeatedly.
Report:
- CLIProxyAPI version/path and local endpoint
- authorized Providers, without account identifiers
- models added or updated
- capability probe results
- conflicts, skipped models, and preserved stale entries
- backup paths and any remaining user action
- effective input/output token limits and their non-secret metadata source
Never include API keys, OAuth URLs containing one-time codes, token file contents, or raw request bodies.
Repair workflow
For an expired or broken model:
- Run
auditand distinguish proxy-down, missing key, missing OAuth, unavailable model, Provider quota, and WorkBuddy-cache failures. - Start or repair the existing service before reinstalling anything.
- For a recovered quota followed by persistent
503 auth_unavailable, follow Quota recovered but 503 persists before reauthorizing. - Rerun
authorize <provider>only when auth is absent or an authentication-specific probe fails. - Rerun
sync --providers <affected-provider> --apply. - Verify a real text request and every declared optional capability.
Do not rotate the WorkBuddy API key merely because a Provider OAuth session changed. The proxy client key and upstream OAuth credentials have different lifecycles.
Read troubleshooting.md for failure classification and rollback guidance.
Add a new CLI Provider
Read both:
- provider-schema.md
- onboarding-new-cli.md
Prefer, in order:
- CLIProxyAPI native OAuth Provider
- official OpenAI-compatible endpoint
- declarative model alias/protocol mapping
- a bounded local adapter as a separately disclosed last resort
Save machine-local manifests under:
~/.config/workbuddy-cli-model-bridge/providers.d/<provider-id>.jsonValidate before use:
python3 <skill-dir>/scripts/bridge.py validate-provider ~/.config/workbuddy-cli-model-bridge/providers.d/<provider-id>.jsonThen authorize and sync by the new Provider ID. A new manifest becomes reusable by every Agent on the same machine without modifying this Skill. Promote it into the public Skill only after isolated tests prove installation, authentication handoff, model selection, capability accuracy, and rollback behavior.
Safety boundaries
Read security-boundaries.md before changing service exposure, credentials, or adding a local adapter.
- Bind the proxy to loopback and keep remote management disabled.
- Store bridge secrets, OAuth files, WorkBuddy config, and credential-bearing backups with mode
0600. - Use only accounts the user owns and respect Provider subscription terms and rate limits.
- Never implement ban evasion, account sharing, automated block reset, token extraction, or hidden traffic cloaking.
- Preserve user-created WorkBuddy models and unrelated CLIProxyAPI configuration.
- Treat Provider manifests as code: validate their source and inspect local overrides before executing login flags.
Completion gate
Completion requires:
- audit has no unresolved security error
- CLIProxyAPI is reachable on loopback with the dedicated client key
- each registered model passed text and streaming probes
- every enabled optional capability passed its probe
- every registered model has sourced input/output limits and passed the bounded output-limit probe
- WorkBuddy loaded the resulting model list
- repeated sync is idempotent
- backups and rollback paths are reported
If any gate remains unproven, report the model as unverified rather than declaring success.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

