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.

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 /plugin install works immediately 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

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. 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:refresh.
2. Live usage status line (optional). Claude offers to wrap your Claude Code status line so Beezi can record the plan-usage numbers Claude Code already computes. No extra requests are made, and any status line you already have keeps rendering unchanged. Declining is fine — usage is still captured, just less often.
3. Crash diagnostics (optional). Claude asks whether Beezi may collect crash reports about the plugin itself. They are off unless you say yes. See Crash Diagnostics.
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.

NOTE

Re-running /beezi:login for an already-linked account is safe. It is the supported way to refresh a changed subscription plan, install the status line later, or resume an interrupted upload of past sessions.

Optional Configuration

Variable	Default	Purpose
BEEZI_API_URL	https://beezi-api-prod.azurewebsites.net/api	Beezi API base URL
BEEZI_MCP_URL	<API URL>/mcp	Beezi MCP server used for the analytics summary
BEEZI_HOME	~/.beezi	Local state root (accounts, queue, cursors, credentials fallback)

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:me	List the accounts linked on this machine, their plan and tracking mode, and which one is the default
/beezi:accounts	Pick which linked account /beezi:analytics reads from
/beezi:logout	Log out one account, or all of them, and delete their stored credentials
/beezi:track	Save the current session's analytics without waiting for it to end
/beezi:sync	Upload past sessions that Beezi does not have yet. Safe to run any time
/beezi:refresh	Re-capture this machine's Claude subscription plan
/beezi:telemetry	Turn plugin crash diagnostics on or off
/beezi:about	Show the installed plugin version, whether a newer one is published, when it was last updated, and how to update

Notes on Individual Commands

/beezi:me tells a missing link apart from a temporary problem. "Not linked" means there is no saved authorization. A temporary failure, or a sign-in renewal in progress, is not a reason to run /beezi:login again.

/beezi:track saves the session the moment the command is submitted, with no model round trip, and shows its result as a system message. It therefore works even when the model is unavailable — an outage, or no credits. It fails only if the machine is not linked, the transcript cannot be found, or the server rejects the report.

/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. 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. It also starts Cowork tracking (see Cowork Sessions).

/beezi: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:about checks for the newest published version every time you run it. If that check fails — for example, offline — it shows the last version it saw and when. "Last updated" 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. See Plugin Updates.

/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.

4. 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. 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:accounts.

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

5. Multiple Accounts

You can link more than one Beezi account to the same machine — for example, accounts in two different workspaces. 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 rules.
• Reading uses one account — the default. /beezi:analytics and /beezi:refresh use the default. Set it with /beezi:accounts; /beezi:me shows 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.

Two users of the same workspace cannot both be linked on one machine — that would count the machine's usage twice. /beezi:login refuses it and links nothing.

6. 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:

claude plugin marketplace update beezi
claude plugin update beezi@beezi

Restart Claude Code after updating. A running session keeps the old version in memory, so the new version takes effect from the next session.

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

Beezi plugin — beezi
  Installed version: 0.34.0
  Latest published:  0.35.0 (checked 2026-10-06 12:00 UTC)
  Last updated here: 2026-10-06 09:20 UTC (first installed 2026-09-10 17:43 UTC)
  Marketplace:       beezi (auto-update on)

Update available: 0.34.0 → 0.35.0. To update:
  - 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.

When you already have the newest version, it says so instead of listing update steps.

7. Crash Diagnostics

Crash diagnostics are off until you turn them on. /beezi:login asks once, and so does a one-time notice at session start. Change your answer any time with /beezi:telemetry:

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

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.

8. 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, prepares repository attribution, notices plan or billing changes, and checks for plugin updates
UserPromptSubmit	Runs the manual save for /beezi:track, and pings live usage
PostToolUse	Saves an incremental checkpoint and a lightweight activity pulse
PermissionRequest	Records time spent waiting for you to approve a tool, so the session timeline shows it as waiting rather than working
PreCompact	Captures usage before the conversation is compacted
SubagentStop	Captures usage when a subagent finishes
Stop / StopFailure	Records turn completion and turn-level failures
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.

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.

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.

9. 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.

10. 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.

Claude Code tells you which one applies at session start, 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.

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.

11. Privacy & Credential Storage

The plugin sends nothing to Beezi until you run /beezi:login, and nothing after /beezi:logout.

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 and a per-skill tally for skill calls; 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, the subscription type, and your plan's usage-limit levels.
• 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.
• 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 opens your browser at Beezi's sign-in service, https://clerk.beezi.ai, and registers 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:about, 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 file. The plan capture reads only the non-secret account fields from it — never a token, never the credentials file.
• 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

12. Troubleshooting

Nothing Is Being Tracked

Problem: Sessions run but no analytics appear in Beezi.

Solution:

1. Run /beezi:me to confirm this machine is linked and that it's the account you expect.
2. Read the message Claude Code shows at session start — it says when a tenant is in audit mode, when analytics are off, or when a repository isn't connected.
3. Run /beezi:track to force a save and read the error it reports.

/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. 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.

/beezi:login Says the Machine Is Already Linked

Not an error. Continue the flow — the plan capture, status line offer, and history upload still run, which is exactly how you refresh a changed subscription plan or finish an interrupted upload.

/beezi:login Says the Workspace Is Already Linked as Another Account

Problem: You tried to link a second account from a workspace that already has an account linked on this machine.

Solution: Nothing was linked. One machine can hold only one account per workspace. Log the other account out with /beezi:logout first if you want to switch.

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, or that it kept the self-reported plan.

Solution: Answer the question when Claude asks it, and run /beezi: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: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.

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:me 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.

Solution: 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.

13. 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:about (your plugin version)
• Your operating system and Claude Code version
• Error messages or screenshots
• If diagnostics are on with /beezi:telemetry correlate, mention it — support can then find your crash reports