Set up Workban Guard in Claude Code and Codex

Step 01

Sign in the Workban CLI

Workban Guard checks your access through your Workban account. If the workban CLI is not set up yet, install it as described on workban.de/einrichten. Create the personal token in Workban under Settings → Tokens, in the workspace that has Workban Guard enabled. Then sign in and check:

workban auth login --api-url https://workban.de/api/v1 --token wb_p_…
workban auth status --api-url https://workban.de/api/v1

Workban Guard uses exactly this token. If you leave the workspace or revoke the token, access to the downloads ends. Installed copies keep running.

Step 02

Claude Code

Add the marketplace to your ~/.claude/settings.json. If the file already has content, only add the key extraKnownMarketplaces:

{
  "extraKnownMarketplaces": {
    "workban-guard": {
      "source": {
        "source": "url",
        "url": "https://guard.workban.de/marketplace.json",
        "headersHelper": "PATH=\"$PATH:$HOME/.local/bin:/usr/local/bin:/opt/homebrew/bin\" workban auth header --api-url https://workban.de/api/v1"
      },
      "autoUpdate": true
    }
  }
}

Then start Claude Code once, a short start is enough: only then does it pick up the marketplace from the settings. Then install:

claude plugin install wbg@workban-guard

Restart Claude Code or type /reload-plugins. To check: /wbg:status shows the state. Ask Claude to run git reset --hard and Workban Guard asks you first.

Claude Code builds the header on every request with workban auth header, so with the token the CLI already stores. The PATH addition finds the CLI even when Claude Code starts without a login shell (desktop app, IDE). With autoUpdate it picks up new versions by itself.

Step 03

Codex CLI

Codex adds marketplaces from a folder or a Git repository. Download the marketplace folder with your Workban token and add it:

mkdir -p ~/.local/share/workban-guard && cd ~/.local/share/workban-guard
curl -fsSL -H "$(workban auth header --http --api-url https://workban.de/api/v1)" \
  -o wbg.zip https://guard.workban.de/download/wbg-marketplace.zip
unzip -oq wbg.zip && rm wbg.zip
codex plugin marketplace add ~/.local/share/workban-guard/workban-guard
codex plugin add wbg@workban-guard

Open Codex, run /hooks and trust the Workban Guard hooks. Only then do they run. To check: $wbg-status.

Step 04

For a project with a team

To give everyone in a project Workban Guard, commit a .claude/settings.json with the marketplace and the plugin. It holds no secret, everyone uses their own Workban account:

{
  "extraKnownMarketplaces": {
    "workban-guard": {
      "source": {
        "source": "url",
        "url": "https://guard.workban.de/marketplace.json",
        "headersHelper": "PATH=\"$PATH:$HOME/.local/bin:/usr/local/bin:/opt/homebrew/bin\" workban auth header --api-url https://workban.de/api/v1"
      },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "wbg@workban-guard": true
  }
}

Each person signs in their workban CLI (step 1), trusts the project folder when Claude Code first starts there and installs once:

claude plugin install wbg@workban-guard --scope project

Project rules live in .workban-guard.json. If code from the project may only go to Claude, use this:

{
  "review": {
    "engines": [
      "claude"
    ]
  }
}

Step 05

Update

Claude Code picks up new versions by itself thanks to autoUpdate. To update right now:

claude plugin marketplace update workban-guard
claude plugin update wbg@workban-guard

For Codex, download the folder again and add the plugin once more. If the hook file changed, Codex asks for your trust again under /hooks.

cd ~/.local/share/workban-guard
curl -fsSL -H "$(workban auth header --http --api-url https://workban.de/api/v1)" \
  -o wbg.zip https://guard.workban.de/download/wbg-marketplace.zip
unzip -oq wbg.zip && rm wbg.zip
codex plugin add wbg@workban-guard

Step 06

Remove

Pausing is often enough: /wbg:pause switches Workban Guard off for at most 8 hours. To remove it completely:

claude plugin uninstall wbg@workban-guard

codex plugin remove wbg@workban-guard
codex plugin marketplace remove workban-guard

Step 07

If something goes wrong

401 on download

The workban CLI is not signed in, or the token was revoked. workban auth status shows where you stand.

403 on download

Workban Guard is not enabled for the workspace of your token. Use a token from the enabled workspace. Or, as an owner or admin, request activation in Workban under Settings → Workban Guard.

workban: command not found

Claude Code does not find the CLI. If it is not in ~/.local/bin, /usr/local/bin or /opt/homebrew/bin, add its folder in the headersHelper.

"isn't installed here"

The plugin is in the project settings but not installed for you yet: claude plugin install wbg@workban-guard --scope project.

"not found in marketplace"

Claude Code has not picked up the marketplace yet. Start Claude Code once, then install again.

Codex checks nothing

The hooks are not trusted yet under /hooks.

node: command not found

The hooks start node. Node.js 22.23.4, 24.22.1 or 26.12.1 (or newer) has to be on the PATH; older versions have known security holes.

Messages in German

Workban Guard talks to the agent in German. The agent still answers you in your language.