Beezi Plugin for Claude Code

Beezi ships an official plugin for Claude Code. Once installed and linked, it reports what each session used — tokens, tool calls, which models ran and at what effort level, which skills and MCP servers were invoked, active time, code-change counts, and the branch or repository the work belongs to. It can also pick up the Cowork sessions Claude Desktop keeps on the same machine.

Everything reported comes from what Claude Code records about a session. The plugin does not send your prompts, your model's responses, or your file contents. See Privacy & Credential Storage for the full list of what it sends.

The plugin signs in with your own Beezi account. You must already be a Beezi user — everything it does happens as you, on your tenant. One machine can be linked to more than one Beezi account, and one account can send analytics to more than one workspace.

1. Requirements

• Claude Code with plugin support.
• Node.js 13.2 or newer, available on your PATH as node.
• Zero dependencies — the plugin runs on Node built-ins alone, so it works immediately after installation with nothing to install or build, on every platform.

Every command and hook the plugin ships is a Node script, so the node binary must be resolvable in the environment Claude Code runs in. Check yours with:

node --version

NOTE

Node 13.2 is the floor because the plugin is ESM-only — that is the first release to load ES modules without a flag. On an older runtime, the scripts cannot start, so no analytics are reported. Any current Node LTS release is comfortably above the floor.

2. Installation

There are two ways to install the plugin: a one-line installer you run in a terminal, or Claude Code's own /plugin commands. Both install the same plugin from the same marketplace.

Option A. Install From a Terminal

On macOS or Linux, run:

curl -fsSL https://beezi.ai/claude/install.sh | bash

On Windows, run this in Windows PowerShell 5.1 or PowerShell 7:

irm https://beezi.ai/claude/install.ps1 | iex

The installer finds Claude Code on this machine and installs the plugin at user scope, so the terminal CLI, the Claude desktop app, and the VS Code and JetBrains extensions all pick it up. If an older version is already installed, it updates it. It shows what it is about to do and asks you to confirm before it changes anything, and it never edits your settings files itself.

On a machine that is not linked to Beezi yet, and when Node is available, the installer then runs a short setup right in the terminal. It asks the same questions as /beezi:login (see below) without starting a Claude Code session:

1. Account. It opens Beezi's sign-in page in your browser.
2. Where analytics go, for accounts in several workspaces.
3. Subscription plan.
4. New workspaces and repositories with no rule, followed by the upload of your past sessions.
5. Default account, when another account is already linked.
6. Crash reports, and the status line when it is not on yet.

Its questions are arrow-key menus (↑/↓, then Enter). Set NO_COLOR to turn the colours off. When setup finishes, restart Claude Code so the running session loads the plugin.

On a machine that is already linked, the installer only installs or updates the plugin and tells you to restart Claude Code; if everything is already up to date, it says there is nothing to do. To add another account or answer the setup questions again, run /beezi:login in Claude Code.

To skip the confirmation prompt in scripted setups, use:

curl -fsSL https://beezi.ai/claude/install.sh | bash -s -- --yes

$env:BEEZI_YES = '1'; irm https://beezi.ai/claude/install.ps1 | iex

With --yes, the installer installs or updates the plugin but does not run the setup. Finish by restarting Claude Code and running /beezi:login.

NOTE

The terminal setup needs an interactive terminal. Without one, it stops and asks you to run /beezi:login in Claude Code instead. If Node is not installed, the installer warns you; install Node from https://nodejs.org and run the installer again to sign in.

Option B. Install From Claude Code

IMPORTANT

Plan mode and auto mode stop the plugin's scripts from running — switch to normal mode before running these steps. Shift+Tab cycles modes.

Step 1. Add the marketplace and install the plugin.

/plugin marketplace add https://github.com/Beezi-AI/beezi-claude-plugin
/plugin install beezi@beezi

Step 2. Link this machine.

/beezi:login

/beezi:login first checks that the link can finish. If the session is in plan mode or auto mode, or cannot write the plugin's local state (for example, inside a sandbox), it stops before anything is changed and tells you what to fix.

It then opens Beezi's sign-in page in your browser and continues once you approve there. After that, it walks a short setup:

1. Where analytics from this machine go (only for an account in several workspaces). The first time, Claude asks "Where should analytics from this machine go?" Pick one workspace to send everything there, Several workspaces… to send everything to each of the workspaces you pick next, or Let me choose per repo to be asked about each repository and folder. Each option previews how many past sessions it would send. If the folder you are working in still has no rule, Claude also asks where its analytics go. See Choosing Where Analytics Go.
2. Subscription plan. Records which Claude plan this machine bills against, so it reports spend accurately. If it cannot be determined, Claude asks you — including an option for machines that pay per token with an API key. Machines that send Claude Code through a custom API endpoint (gateway) get one extra question first: what pays for that usage. Machines that sign in with a Claude setup token (CLAUDE_CODE_OAUTH_TOKEN) get their plan from Beezi instead — see /beezi:settings refresh.
3. New workspaces and repositories with no rule (only for an account in several workspaces). If you joined a workspace since this machine was last set up, Claude asks which repositories and folders should also send analytics to it. If past sessions ran in repositories or folders that have no rule yet, Claude asks where each one goes.
4. Past sessions. Uploads the Claude Code history already on this machine, so your analytics are populated from the start rather than beginning at zero. This can take several minutes and prints progress as it goes.
5. Default account (only when another account is already linked). Claude asks whether the account you just linked should become the one /beezi:analytics reads from.

After that, it tracks work automatically. There is nothing else to run.

The live usage status line and crash reports are not part of /beezi:login. Turn them on with /beezi:settings (see Crash Diagnostics and Live Usage Status Line), or answer them in the terminal setup.

NOTE

Re-running /beezi:login for an already-linked account is safe. It is the supported way to refresh a changed subscription plan, answer setup questions you skipped, or resume an interrupted upload of past sessions.

Optional Configuration

Variable	Default	Purpose
BEEZI_API_URL	https://api.beezi.ai/api	Beezi API base URL
BEEZI_MCP_URL	The API URL followed by /mcp	Beezi MCP server used for the analytics summary
BEEZI_HOME	~/.beezi	Local state root (accounts, queue, cursors, credentials fallback)
BEEZI_DEBUG	Not set	Set to 1 to show the full error text instead of "Something went wrong"

3. Commands

Commands are slash commands shipped by the plugin. Each one runs a fixed local script — Claude is instructed not to read or inspect files on your behalf, and never to echo a token.

Command	Purpose
/beezi:login	Link a Beezi account to this machine and run the setup above. Run it again to add another account
/beezi:status	Show your sign-in, workspaces, where this folder's analytics go, your Claude plan, and the plugin version with how to update it
/beezi:settings	Show and change where analytics go, your default account and Claude plan, crash reports, and the status line
/beezi:sync	Upload past sessions that Beezi does not have yet. Safe to run any time
/beezi:release-notes	Show what changed in the installed version and the versions before it
/beezi:logout	Log out one account, or all of them, and delete their stored credentials

/beezi:settings opens a menu when run on its own. You can also go straight to one part of it:

Command	Effect
/beezi:settings show	Print the current settings and change nothing
/beezi:settings rules	Choose where each repository or folder sends its analytics, or stop tracking one. rules add adds a rule for the current folder; rules remove 2 removes rule R2
/beezi:settings new-folders	For an account in several workspaces: where analytics go for a repository or folder with no rule
/beezi:settings account	Refresh your Claude plan, or pick the default account when several are linked
/beezi:settings refresh	Re-capture this machine's Claude subscription plan
/beezi:settings undo	Put your last rule change back
/beezi:settings telemetry	Turn plugin crash reports on or off. See Crash Diagnostics
/beezi:settings statusline	Turn Beezi's live usage status line, and its optional badge, on or off

Adding show after a section name (for example, /beezi:settings rules show) prints that section without changing anything.

Notes on Individual Commands

/beezi:status is read-only. It tells a missing link apart from a temporary problem: "not linked" means there is no saved authorization, while a temporary failure, or a sign-in renewal in progress, is not a reason to run /beezi:login again. It also checks for the newest published plugin version every time you run it. See Plugin Updates for an example.

/beezi:sync uploads every past session still on this machine that Beezi does not already have. It asks Beezi how much of each session it already holds and continues from exactly there, so it never double-counts. Run it as often as you like — "everything is already uploaded" is a success, not an error. Sessions that are still running are skipped and uploaded once they finish. Your workspace's plan can still refuse the upload, for example when its audit period has ended. With several accounts linked, it syncs each one in turn. For an account in several workspaces, it first asks about new workspaces and about repositories and folders with no rule, then sends each past session where its own repository or folder routes. It also starts Cowork tracking (see Cowork Sessions).

/beezi:settings refresh updates the plan this machine reports. On a machine that signs in with a Claude setup token (CLAUDE_CODE_OAUTH_TOKEN), the plan cannot be read locally, so Beezi is asked instead. If Beezi does not know it yet, Claude lets you pick one of your existing subscriptions, name the plan, or enter the email or account id the token belongs to. It uses the default account unless you name another.

/beezi:release-notes shows the notes for the installed version, a table of the three versions before it, and a line when a newer version is published. Use /beezi:release-notes all to list every version, or a version number such as /beezi:release-notes 0.39.0 to show one.

/beezi:logout asks which account to log out, with an "All accounts" option. If you remove the default account while others remain, it asks which one becomes the new default. It always signs out locally, even when it cannot reach the server, so a machine can never be left holding credentials it cannot revoke.

NOTE

Earlier versions had separate commands that are now part of /beezi:status and /beezi:settings: /beezi:me and /beezi:about are covered by /beezi:status; /beezi:accounts, /beezi:refresh and /beezi:telemetry are now /beezi:settings account, /beezi:settings refresh and /beezi:settings telemetry. /beezi:track was removed — sessions are saved automatically as you work.

4. Choosing Where Analytics Go

Session Banner

Every new session starts with a short banner: who you are signed in as, your workspace, and where this folder's analytics go. For example:

Beezi ✓ jane@example.com, workspace Acme
  web-app → Acme (default)
  Change with /beezi:settings rules

The banner also tells you when nothing is sent from this folder — for example, when the repository is not connected to a Beezi project, when it is marked as not tracked, when it has no rule yet, or when the workspace is in audit mode or has analytics turned off. With several accounts linked, it shows one line per account.

Accounts in One Workspace

An account in a single workspace sends everything to that workspace. You can still exclude repositories and folders: run /beezi:settings rules and choose Don't track this repo (or folder), or pick another repository or folder from the ones you use most. To track an excluded repository or folder again, run /beezi:settings rules from inside it and choose to track it again.

Accounts in Several Workspaces

For an account in several workspaces, Beezi decides per repository or folder:

• Rules. A rule sends every session in one repository, or under one folder, to the workspaces it names — or marks it as not tracked. A repository is matched by its origin remote, however it was cloned. A repository rule wins first, then the folder rule with the longest matching path. Sessions in your home folder, /, or a temp folder share one "outside a project" rule. A new or changed rule applies at once to sessions already open there.
• New folders. This setting decides what happens in a repository or folder with no rule: Ask me (the default), Send to the workspaces you pick, or Don't send. Change it with /beezi:settings new-folders.
• Ask me. While New folders is Ask me, the first session in a repository or folder with no rule asks once where its analytics go, and your answer becomes its rule. That session's data waits on this machine until you answer.
• Joining a workspace. After you join another workspace, the next session (and the next /beezi:login or /beezi:sync) asks which repositories and folders should also send analytics to it. Their past sessions are sent there too.

"Don't track" cannot be combined with a workspace in the same answer — if you pick both, Claude asks again. /beezi:settings undo puts back your last rule change.

NOTE

A remote that uses an SSH host alias from ~/.ssh/config (for example, git@github-work:org/repo) is matched by the alias, so its rule does not match other clones of the same repository.

Live Usage Status Line

Beezi can wrap your Claude Code status line to record the plan-usage numbers Claude Code already computes for it. No extra requests are made, and any status line you already have keeps rendering unchanged. Turn it on with /beezi:settings statusline on. Without it, usage is still captured, just less often.

The status line can also show a badge at the end — for example, Beezi → Acme — naming where this folder's analytics go. It is off by default; turn it on with /beezi:settings statusline badge on.

5. Analytics Summary

Run /beezi:analytics for a short personal read — spend, sessions, top model, an alert status, and up to three recommendations. You can also just ask Claude for your Beezi analytics summary.

The default window is the last 7 days; use /beezi:analytics 30d to widen it. For an account in several workspaces, add a workspace name to choose which one is read, for example /beezi:analytics 7d Acme. The summary always covers only the person asking, whatever their role — it is a personal read, not a team report. The figures come from Beezi; the wording is generated by your own model.

With several accounts linked, the summary reads from the default account. Change it with /beezi:settings account.

If the machine isn't linked or authentication fails, Claude replies, "Sign in to Beezi first."

6. Multiple Accounts

You can link more than one Beezi account to the same machine — for example, accounts in two different organizations. Run /beezi:login once per account.

• Tracking goes to every linked account. Each session is reported to each account, following that account's own tracking mode and rules.
• Reading uses one account — the default. /beezi:analytics and /beezi:settings refresh use the default. Set it with /beezi:settings account; /beezi:status marks which one it is.
• To remove an account, use /beezi:logout.

IMPORTANT

The browser signs in as whichever Beezi account it is already signed in as. To add a different account, sign out of Beezi in the browser first, or finish the sign-in in a private window.

Do not link two users of the same workspace on one machine — the machine's usage would then reach that workspace twice.

7. Plugin Updates

At session start, the plugin checks whether a newer version has been published. If there is one, Claude Code shows a one-line notice with the exact commands to run, for example:

Beezi: a newer beezi is published — 0.40.0 → 0.40.1. Run: claude plugin marketplace update beezi, then claude plugin update beezi@beezi — then restart Claude Code to apply it.

Restart Claude Code after updating. A running session keeps the old version in memory, so the new version takes effect from the next session. Running the terminal installer again also updates an older version.

To check at any time, run /beezi:status:

Beezi
  Account       ✓ jane@example.com, signed in
  Workspace     Acme (Owner)
  This repo     web-app → Acme (default)
  Claude plan   Max 5x
  This machine  status line on, crash reports on
  Plugin        0.40.0. Update available: 0.40.1
  Updated here  2026-10-23 09:20 UTC (first installed 2026-09-10 17:43 UTC)
  Marketplace   beezi (auto-update on)

To update to 0.40.1:
  - In Claude Code: run /plugin and update beezi from the beezi marketplace.
  - Or from a terminal:
      claude plugin marketplace update beezi
      claude plugin update beezi@beezi
  Then restart Claude Code to apply it.
  Auto-update is on for this marketplace, so Claude Code also installs it on its own at startup.

Change settings with /beezi:settings

When you already have the newest version, the Plugin line says so and no update steps are listed. If the version check fails — for example, offline — it shows the last version it saw and when. "Updated here" is when Claude Code last installed or updated the plugin on this machine. It is unknown for a copy loaded from a local folder rather than installed from the marketplace.

To see what changed, run /beezi:release-notes.

8. Crash Diagnostics

Crash diagnostics are off until you turn them on. A one-time notice at session start asks, and so does the terminal setup. Change your answer any time with /beezi:settings telemetry:

Command	Effect
/beezi:settings telemetry correlate	Recommended. Diagnostics on, with a random installation ID attached, so support can find your reports
/beezi:settings telemetry on	The same diagnostics, anonymous, with no installation ID
/beezi:settings telemetry anonymous	Keep diagnostics on, and delete the installation ID and the reports that carry it
/beezi:settings telemetry off	Turn everything off and delete reports that have not been sent yet
/beezi:settings telemetry	Show the current setting and offer to change it

Reports contain only facts about the plugin's own failures: plugin and Claude Code versions, the operating system, which plugin file failed, and the authentication state at that moment. They never contain your code, prompts, file paths, or repository names.

Reports are sent without your sign-in token, so the plugin can still report a failure when sign-in itself is what broke. Unsent reports are kept locally for at most 14 days.

9. How Reporting Works

The plugin registers hooks on Claude Code's session lifecycle. Each hook is a small Node script that runs locally, reads the session transcript, and reports a summary to Beezi.

Hook	What it does
SessionStart	Verifies each linked account, shows the session banner, asks where analytics go for a folder with no rule, notices plan or billing changes, checks for plugin updates, and starts the background workers
UserPromptSubmit	Records the session's permission mode (used by the /beezi:login checks), and captures live plan usage
PostToolUse	Saves a checkpoint after a git commit, git switch or git checkout, and a periodic checkpoint while a long turn runs
PermissionRequest	Records time spent waiting for you to approve a tool, so the session timeline shows it as waiting rather than working
PreCompact	Captures live plan usage before the conversation is compacted
SubagentStop	Captures live plan usage when a subagent finishes
Stop	Saves a checkpoint and the activity timeline at the end of each turn, and notes which plugins this project enables
StopFailure	Runs instead of Stop when a turn fails on an API error: reports the error and saves the usage the turn spent
SessionEnd	Ships the final session report

Reporting is incremental, and overlapping hook runs never double-count the same work.

Each session also gets an activity timeline — working, planning, waiting for you, idle, and breaks. Waiting time is split by what Claude was waiting for: a plan approval, an answer to a question, a tool approval, or your next instruction.

What Gets Attributed Where

Work is attributed to a repository when the session resolves to a git repository root with an origin remote. Each part of the session is attributed to the repository it actually ran in — so research turns, thinking, and whole subagents land where the work happened, not wherever the session was launched. Which workspace receives it follows your rules (see Choosing Where Analytics Go).

NOTE

Work outside any git repository, or in a repository with no reachable origin, is not discarded. It is reported under a folder label — only the folder's own name travels, never the path around it.

Session Cost

For past sessions, the plugin uses the cost record Claude Code writes into each session — Claude's own number for what the session cost. The usual breakdown (repository and branch, plan, tools, models, timeline) is still sent with it. A background worker uploads these cost records about once an hour.

MCP Bridge

The plugin ships a stdio bridge that forwards MCP traffic to the Beezi server, authenticated with the default account's credentials stored by /beezi:login — there is no second sign-in prompt for MCP. The bridge is generic: it exposes whatever tools the server offers for your account, which is how the analytics summary stays current without shipping its workflow in the plugin.

10. Cowork Sessions

On Windows and macOS, the plugin also reads the local cache Claude Desktop keeps for Cowork sessions and reports their model usage and cost. Linux is not supported.

• Run /beezi:sync once on the machine running Claude Desktop. It uploads cached Cowork sessions and starts a background worker that tracks new ones live.
• The worker also starts after a successful login and at Claude Code session start and stop.
• It runs while Claude Desktop is open and stops a couple of minutes after Desktop closes. Nothing is installed as a system service — the next session, login, or /beezi:sync starts it again.
• Updates arrive shortly after Claude Desktop records a finished turn. It is not a live token meter for a turn that is still running.

Only model token and cost counters and session times are sent. Prompts, responses, tool inputs, and local folder paths are not. Cowork sessions are named Cowork in Beezi.

NOTE

The plugin must run on the same machine as Claude Desktop. Claude Desktop can drop old entries from its cache, and cloud sessions never opened on this machine may be missing, so the cache is not a complete history.

11. Availability

The plugin is free to install. What it reports depends on your Beezi tenant.

• Live tracking — the normal mode. Past sessions are uploaded when you link the machine, and new sessions are reported as they happen.
• Audit mode — past sessions can be uploaded, but new sessions are not tracked.
• Off — analytics are turned off for the workspace.

The session banner tells you when audit mode or "analytics off" applies, and points at the next step when there is one. A tenant's mode is determined by its Beezi plan — if tracking isn't what you expect, check your plan in the Beezi portal or ask your tenant owner.

The history import that runs during /beezi:login is one-time per account. After a clean run it is sealed on the Beezi side and cannot be run again. It can only upload sessions that are still on disk: Claude Code deletes local transcripts older than its cleanupPeriodDays setting (30 days by default).

IMPORTANT

If you have Claude Code history on more than one machine, run /beezi:login on each of them before the import is sealed. A sealed import cannot be reopened.

Which repositories can be reported also depends on the tenant: some accept only sessions from repositories connected to Beezi, and reject the rest.

12. Privacy & Credential Storage

The plugin sends nothing to Beezi until you run /beezi:login (or sign in through the terminal setup), and nothing after /beezi:logout. Repositories and folders you mark as not tracked send no session analytics and no project plugin list.

What Beezi Receives

All analytics go to one place: the Beezi API. Per session, and per repository and branch the session touched:

• Usage numbers — input, output, and cache token counts per model and effort level; tool-call counts by category (file, search, internet, MCP, shell, skill, other), with a per-server tally for MCP calls, a per-skill tally for skill calls, and the plugin each skill belongs to; active time; start and end times and your time zone; and the activity timeline. For subagents, the agent type and spawn depth.
• Code-change counts — lines added and removed, and files changed per file extension, plus the line count of the CLAUDE.md the work ran under.
• Where the work happened — the repository's origin remote with any credentials, query strings, and local paths stripped, the branch name and Beezi task id, or a folder-name-only label for work outside a repository.
• The session name shown in Claude Code's /status. Claude Code may derive it from your first prompt.
• Claude API errors — the error type and Claude Code's error message, such as a rate-limit or billing error.
• This machine and its Claude account — the machine's hostname, your Claude account id and email, your Claude organization's id and name, the subscription type, and your plan's usage-limit levels. On a machine that signs in with a Claude setup token, the account id, email, and organization are left out, and the token's fingerprint identifies the subscription instead.
• A fingerprint of each Claude credential set in this machine's environment (CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, and, when used, ANTHROPIC_AUTH_TOKEN or AWS_ACCESS_KEY_ID). A fingerprint is the first 12 characters, the last 4, and the length. It lets Beezi tell which subscription pays for the usage. The credential cannot be rebuilt from it and is never sent.
• The Claude Code plugins enabled on this machine — about once an hour, the name, marketplace, and version of each plugin switched on in enabledPlugins: in your user settings, and in the project settings of folders you used Claude Code in during the last 30 days, together with that folder's repository. A project's plugins go only to the workspaces that folder's analytics go to, never for a folder you do not track, and never to a workspace without live tracking.
• Crash diagnostics, only if you turn them on — see Crash Diagnostics.

Other Network Requests

Two other requests carry none of the data above:

• Sign-in — /beezi:login and the terminal setup open your browser at Beezi's sign-in service, https://clerk.beezi.ai, and register this machine there as a sign-in client named after its hostname. /beezi:logout revokes it.
• Update check — at session start, and when you run /beezi:status or /beezi:release-notes, the plugin reads the public marketplace file from https://raw.githubusercontent.com to see whether a newer version is out. It sends nothing but the request itself.

What Never Leaves the Machine

• Your prompts, the model's responses, your code, diffs, and the contents of your files. (The session name is the one exception noted above — Claude Code may build it from your first prompt.)
• Tool inputs and outputs.
• Your Beezi and Claude sign-in tokens, and your API keys.
• The contents of your local Claude configuration and settings files. The plan capture reads only the non-secret account fields — never a token, never the credentials file — and the plugin list reads only the enabledPlugins entries.
• File paths, and the path around a folder. Only a folder's own name is ever sent for work outside a repository.

Credential Storage

Each linked account's /beezi:login token is stored in your operating system's own secret store via its built-in CLI — no native module and no extra install:

Platform	Where the token is stored
macOS	The login keychain
Linux	Secret Service / libsecret, when available
Windows	DPAPI (user-bound encryption); the ciphertext is kept in a file
Fallback	A permission-restricted (0600) file under BEEZI_HOME/accounts/ (default ~/.beezi/accounts/) when no store is available

13. Troubleshooting

Nothing Is Being Tracked

Problem: Sessions run but no analytics appear in Beezi.

Solution:

1. Run /beezi:status to confirm this machine is linked, that it's the account you expect, and where this folder's analytics go.
2. Read the session banner — it says when a repository isn't connected, has no rule yet, or is not tracked, and when a workspace is in audit mode or has analytics off.
3. Run /beezi:settings rules to check, or change, the rule for this repository or folder.

The Banner Says This Folder Has No Rule Yet

Problem: The session banner says the folder has no rule yet and nothing is sent until you choose where it goes.

Solution: Your account is in several workspaces and New folders is set to Ask me. Answer the question Claude asks at session start, or run /beezi:settings rules and add a rule for this folder. The session's data waits on the machine until you do. To stop being asked, pick a default with /beezi:settings new-folders.

/beezi:login Stops Before Signing In

Problem: Login prints lines starting with ✗ and does nothing else, or Claude says the plugin's scripts are blocked.

Solution: Login stopped on purpose, so the machine is not left half-linked. Do what the message says — usually press Shift+Tab to leave plan mode or auto mode, or run Claude Code outside the sandbox — then run /beezi:login again.

Sign-in Fails With a Network Error

Problem: The browser sign-in cannot reach Beezi.

Solution: A sandboxed session can block outbound network requests even when it can write files. Run /beezi:login outside the sandbox, or use the terminal installer. A failed sign-in never removes an authorization that was already on the machine.

Commands Are Blocked or Never Run

Problem: A /beezi:* command produces no output, or Claude describes what it would do instead of running it.

Solution: Check which mode Claude Code is in. Plan mode and auto mode stop the plugin's scripts from running. Press Shift+Tab to cycle modes, switch to normal mode, and run the command again.

Commands Fail With a Node Error

Problem: A Beezi command exits immediately, or reports that node was not found or that it cannot load a module.

Solution:

1. Run node --version. It must report 13.2 or newer.
2. If nothing is reported, Node is not on the PATH that Claude Code uses. Install Node (any current LTS) and restart Claude Code so it picks up the updated PATH.
3. If the version is older than 13.2, upgrade — the plugin is ESM-only and cannot start on earlier runtimes.

A Command Says "Something Went Wrong"

Problem: A command prints "Something went wrong. Re-run with BEEZI_DEBUG=1 to see details."

Solution: Set the environment variable BEEZI_DEBUG=1 before starting Claude Code, repeat the step, and include the full error text when you contact support.

The Installer Cannot Install the Plugin

Problem: The installer says this Claude Code can't install plugins from the command line, or that the Claude Code CLI isn't installed.

Solution: Update Claude Code (claude update) and run the installer again. If you only use the Claude Code extension in your editor, the installer offers to open the extension's plugin dialog instead; if you use the Claude desktop app, open its Code tab once and run the installer again. You can always install from inside Claude Code with the /plugin commands in Installation.

The Terminal Setup Warns About CLAUDE_CODE_OAUTH_TOKEN

Problem: The setup prints a warning that your shell sets CLAUDE_CODE_OAUTH_TOKEN, but Claude Code hides it from plugins.

Solution: Claude Code does not pass a token set only in your shell to plugins, so Beezi cannot count usage against that key. Add the token to the env block in ~/.claude/settings.json, then run the installer or /beezi:login again.

/beezi:login Says the Machine Is Already Linked

Not an error. Continue the flow — the plan capture, any open questions about where analytics go, and the history upload still run, which is exactly how you refresh a changed subscription plan or finish an interrupted upload.

Authentication Is Temporarily Unavailable

Problem: Session start or a command says authentication is temporarily unavailable, or a renewal is in progress.

Solution: The machine is still linked — the saved sign-in just could not be read at that moment. Do not run /beezi:login; try again shortly.

The Machine's Link Was Rejected

Problem: Session start warns that this machine's link was rejected and analytics are not being tracked.

Solution: Run /beezi:login to authorize the machine again.

The Subscription Plan Could Not Be Resolved

Problem: Login reports that no Claude subscription info was found, that it kept the self-reported plan, or session start says the plan info is missing or stale.

Solution: Answer the question when Claude asks it, and run /beezi:settings refresh later if your plan changes. If this machine pays per token, choose the API-key option — otherwise its spend is reported under a subscription tier it does not have.

Session Start Asks About a Setup Token or a Custom API Endpoint

Problem: Session start says Beezi does not know which subscription this machine's setup token bills, or that billing goes through a custom API endpoint and is reported as "unknown".

Solution:

• Setup token — run /beezi:settings refresh and pick or name the subscription the token belongs to.
• Custom API endpoint — run /beezi:login and answer whether your Claude subscription, the gateway, or an API key pays for the usage.

Live Plan-Usage Capture Is Off

Problem: Session start says your status line no longer runs Beezi's wrapper.

Solution: Another tool or a manual edit replaced the status line. Run /beezi:settings statusline on to wrap it again; your own status line keeps rendering unchanged.

Older Sessions Show Unknown Billing

Problem: Some sessions uploaded by older plugin versions show Unknown billing in Beezi.

Solution: Update the plugin. It repairs these sessions in the background over the next few hours. To repair them right away, run /beezi:sync.

The History Import Has Already Been Used

Problem: /beezi:login says the one-time import has already been used.

Solution: That is final — the import runs once per account and cannot be re-run. If the message suggests it, upgrade your workspace plan to track new sessions live.

/beezi:sync Says Uploads Are Disabled

Problem: /beezi:sync reports that uploads are disabled for this workspace because the audit period has ended.

Solution: Expected — the workspace's plan no longer accepts uploads. Upgrade the plan, or ask your tenant owner, to keep tracking.

No beezi Tools Available

Problem: Claude reports it cannot find the Beezi MCP tools, so the analytics summary is unavailable.

Solution:

1. Run /mcp and confirm the beezi server is connected.
2. If it is connected but no tools are listed, MCP tools are switched off for your Beezi deployment — a Beezi admin can enable them.

Authentication Errors During MCP Calls

Problem: MCP calls fail with an authentication error.

Solution: Run /beezi:status to check the default account, then run /beezi:login again for that account if it is no longer linked.

Some Past Sessions Were Not Uploaded

Problem: The upload reports that a repository is not connected to Beezi, or that some sessions were not sent this time.

Solution: A repository that is not connected is expected on a tenant that only accepts connected repositories. Connect the repository to a Beezi project if that work should be tracked; otherwise, the rejection is correct. Sessions "not sent this time" belong to repositories or folders you skipped a question for — run /beezi:sync to be asked again, or add a rule with /beezi:settings rules.

14. Getting Help

If you encounter issues not covered here:

• Support Email: hello@beezi.ai
• Check Beezi Status: Verify no ongoing service issues

When contacting support, include:

• Your Beezi tenant ID
• The command or skill you ran, and its exact output
• The output of /beezi:status (it includes your plugin version)
• Your operating system and Claude Code version
• Error messages or screenshots
• If diagnostics are on with /beezi:settings telemetry correlate, mention it — support can then find your crash reports